Gemini Developer API

برای دسترسی به مدل‌های Gemini Pro و Flash، به توسعه‌دهندگان اندروید توصیه می‌کنیم که از Gemini Developer API با استفاده از Firebase AI Logic استفاده کنند. این به شما امکان می دهد بدون نیاز به کارت اعتباری شروع به کار کنید و یک ردیف رایگان سخاوتمندانه را فراهم می کند. هنگامی که ادغام خود را با یک پایگاه کاربر کوچک تأیید کردید، می توانید با تغییر به سطح پولی مقیاس کنید.

تصویری از یک برنامه اندروید که حاوی اندروید Firebase است   SDK. یک فلش از SDK به Firebase در یک محیط Cloud اشاره می کند. از   Firebase، یک فلش دیگر به Gemini Developer API اشاره می کند که به آن متصل است   Gemini Pro & Flash، همچنین در فضای ابری.
شکل 1. معماری ادغام منطق هوش مصنوعی Firebase برای دسترسی به Gemini Developer API.

شروع کردن

قبل از اینکه مستقیماً از برنامه خود با Gemini API تعامل داشته باشید، ابتدا باید چند کار را انجام دهید، از جمله آشنایی با درخواست ها و همچنین راه اندازی Firebase و برنامه خود برای استفاده از SDK.

با دستورات آزمایش کنید

آزمایش کردن با فرمان‌ها می‌تواند به شما کمک کند بهترین عبارت، محتوا و قالب را برای برنامه Android خود پیدا کنید. Google AI Studio یک IDE است که می‌توانید از آن برای نمونه‌سازی اولیه و طراحی درخواست‌ها برای موارد استفاده برنامه‌تان استفاده کنید.

ایجاد دستور مناسب برای مورد استفاده شما بیشتر هنر است تا علم، که آزمایش را حیاتی می کند. می‌توانید در مستندات Firebase درباره درخواست بیشتر بیاموزید.

هنگامی که از درخواست خود راضی بودید، روی دکمه "<>" کلیک کنید تا کدهایی را دریافت کنید که می توانید به کد خود اضافه کنید.

یک پروژه Firebase راه اندازی کنید و برنامه خود را به Firebase متصل کنید

هنگامی که آماده تماس با API از برنامه خود شدید، دستورالعمل های «مرحله 1» راهنمای شروع Firebase AI Logic را برای راه اندازی Firebase و SDK در برنامه خود دنبال کنید.

وابستگی Gradle را اضافه کنید

وابستگی Gradle زیر را به ماژول برنامه خود اضافه کنید:

کاتلین

dependencies {
  // ... other androidx dependencies

  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:34.2.0"))

  // Add the dependency for the Firebase AI Logic library When using the BoM,
  // you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
}

جاوا

dependencies {
  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:34.2.0"))

  // Add the dependency for the Firebase AI Logic library When using the BoM,
  // you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")

  // Required for one-shot operations (to use `ListenableFuture` from Guava
  // Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive
  // Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

مدل مولد را راه اندازی کنید

با نمونه سازی یک GenerativeModel و مشخص کردن نام مدل شروع کنید:

کاتلین

val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .generativeModel("gemini-2.5-flash")

جاوا

GenerativeModel firebaseAI = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-2.5-flash");

GenerativeModelFutures model = GenerativeModelFutures.from(firebaseAI);

درباره مدل‌های موجود برای استفاده با Gemini Developer API بیشتر بیاموزید. همچنین می توانید درباره پیکربندی پارامترهای مدل اطلاعات بیشتری کسب کنید.

با Gemini Developer API از برنامه خود تعامل داشته باشید

اکنون که Firebase و برنامه خود را برای استفاده از SDK تنظیم کرده اید، آماده تعامل با Gemini Developer API از برنامه خود هستید.

تولید متن

برای ایجاد یک پاسخ متنی، با دستور شما generateContent() فراخوانی کنید.

کاتلین

scope.launch {
  val response = model.generateContent("Write a story about a magic backpack.")
}

جاوا

Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        [...]
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

تولید متن از تصاویر و رسانه های دیگر

همچنین می‌توانید متنی را از یک درخواست تولید کنید که شامل متن به اضافه تصاویر یا رسانه‌های دیگر است. هنگامی که با generateContent() تماس می گیرید، می توانید رسانه را به عنوان داده درون خطی ارسال کنید.

به عنوان مثال، برای استفاده از یک بیت مپ، از نوع محتوای image استفاده کنید:

کاتلین

scope.launch {
  val response = model.generateContent(
    content {
      image(bitmap)
      text("what is the object in the picture?")
    }
  )
}

جاوا

Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("what is the object in the picture?")
        .build();

ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        [...]
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

برای ارسال فایل صوتی، از نوع محتوای inlineData استفاده کنید:

کاتلین

val contentResolver = applicationContext.contentResolver
val inputStream = contentResolver.openInputStream(audioUri).use { stream ->
    stream?.let {
        val bytes = stream.readBytes()

        val prompt = content {
            inlineData(bytes, "audio/mpeg")  // Specify the appropriate audio MIME type
            text("Transcribe this audio recording.")
        }

        val response = model.generateContent(prompt)
    }
}

جاوا

ContentResolver resolver = getApplicationContext().getContentResolver();

try (InputStream stream = resolver.openInputStream(audioUri)) {
    File audioFile = new File(new URI(audioUri.toString()));
    int audioSize = (int) audioFile.length();
    byte audioBytes = new byte[audioSize];
    if (stream != null) {
        stream.read(audioBytes, 0, audioBytes.length);
        stream.close();

        // Provide a prompt that includes audio specified earlier and text
        Content prompt = new Content.Builder()
              .addInlineData(audioBytes, "audio/mpeg")  // Specify the appropriate audio MIME type
              .addText("Transcribe what's said in this audio recording.")
              .build();

        // To generate text output, call `generateContent` with the prompt
        ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
        Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
            @Override
            public void onSuccess(GenerateContentResponse result) {
                String text = result.getText();
                Log.d(TAG, (text == null) ? "" : text);
            }
            @Override
            public void onFailure(Throwable t) {
                Log.e(TAG, "Failed to generate a response", t);
            }
        }, executor);
    } else {
        Log.e(TAG, "Error getting input stream for file.");
        // Handle the error appropriately
    }
} catch (IOException e) {
    Log.e(TAG, "Failed to read the audio file", e);
} catch (URISyntaxException e) {
    Log.e(TAG, "Invalid audio file", e);
}

و برای ارائه یک فایل ویدئویی، از نوع محتوای inlineData استفاده کنید:

کاتلین

val contentResolver = applicationContext.contentResolver
contentResolver.openInputStream(videoUri).use { stream ->
  stream?.let {
    val bytes = stream.readBytes()

    val prompt = content {
        inlineData(bytes, "video/mp4")  // Specify the appropriate video MIME type
        text("Describe the content of this video")
    }

    val response = model.generateContent(prompt)
  }
}

جاوا

ContentResolver resolver = getApplicationContext().getContentResolver();

try (InputStream stream = resolver.openInputStream(videoUri)) {
    File videoFile = new File(new URI(videoUri.toString()));
    int videoSize = (int) videoFile.length();
    byte[] videoBytes = new byte[videoSize];
    if (stream != null) {
        stream.read(videoBytes, 0, videoBytes.length);
        stream.close();

        // Provide a prompt that includes video specified earlier and text
        Content prompt = new Content.Builder()
                .addInlineData(videoBytes, "video/mp4")
                .addText("Describe the content of this video")
                .build();

        // To generate text output, call generateContent with the prompt
        ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
        Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
            @Override
            public void onSuccess(GenerateContentResponse result) {
                String resultText = result.getText();
                System.out.println(resultText);
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, executor);
    }
} catch (IOException e) {
    e.printStackTrace();
} catch (URISyntaxException e) {
    e.printStackTrace();
}

به طور مشابه شما همچنین می توانید اسناد PDF ( application/pdf ) و متن ساده ( text/plain ) را با ارسال نوع MIME مربوطه خود به عنوان پارامتر ارسال کنید.

چت چند نوبتی

همچنین می توانید از مکالمات چند نوبتی پشتیبانی کنید. یک چت را با تابع startChat() راه اندازی کنید. می توانید به صورت اختیاری یک تاریخچه پیام به مدل ارائه دهید. سپس تابع sendMessage() را برای ارسال پیام های چت فراخوانی کنید.

کاتلین

val chat = model.startChat(
    history = listOf(
        content(role = "user") { text("Hello, I have 2 dogs in my house.") },
        content(role = "model") { text("Great to meet you. What would you like to know?")   }
    )
)

scope.launch {
   val response = chat.sendMessage("How many paws are in my house?")
}

جاوا

Content.Builder userContentBuilder = new Content.Builder();
userContentBuilder.setRole("user");
userContentBuilder.addText("Hello, I have 2 dogs in my house.");
Content userContent = userContentBuilder.build();

Content.Builder modelContentBuilder = new Content.Builder();
modelContentBuilder.setRole("model");
modelContentBuilder.addText("Great to meet you. What would you like to know?");
Content modelContent = userContentBuilder.build();

List<Content> history = Arrays.asList(userContent, modelContent);

// Initialize the chat
ChatFutures chat = model.startChat(history);

// Create a new user message
Content.Builder messageBuilder = new Content.Builder();
messageBuilder.setRole("user");
messageBuilder.addText("How many paws are in my house?");

Content message = messageBuilder.build();

// Send the message
ListenableFuture<GenerateContentResponse> response = chat.sendMessage(message);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

تولید تصاویر

مدل Gemini 2.5 Flash Image (با نام مستعار نانو موز) می تواند تصاویر را با استفاده از دانش و استدلال جهانی تولید و ویرایش کند. این تصاویر مرتبط با زمینه را تولید می کند و خروجی های متن و تصویر را به طور یکپارچه با هم ترکیب می کند یا در هم می آمیزد. همچنین می‌تواند تصاویر بصری دقیقی با دنباله‌های متن طولانی ایجاد کند و از ویرایش تصویر مکالمه با حفظ متن پشتیبانی می‌کند.

به عنوان جایگزینی برای Gemini، می‌توانید از مدل‌های Imagen استفاده کنید، به‌ویژه برای تولید تصاویر با کیفیت بالا که نیاز به فوتورئالیسم، جزئیات هنری یا سبک‌های خاص دارد. با این حال، برای اکثر موارد استفاده از سمت مشتری برای برنامه های اندروید، Gemini بیش از حد کافی خواهد بود.

این راهنما نحوه استفاده از مدل Gemini 2.5 Flash Image با استفاده از Firebase AI Logic SDK برای اندروید را شرح می دهد. برای جزئیات بیشتر در مورد تولید تصاویر با Gemini، به مستندات ایجاد تصاویر با Gemini در Firebase مراجعه کنید. اگر علاقه مند به استفاده از مدل های Imagen هستید، مستندات را بررسی کنید.

Google AI Studio قابلیت های تولید تصویر را نشان می دهد.
شکل 1. از Google AI Studio برای اصلاح درخواست های تولید تصویر خود استفاده کنید

مدل مولد را راه اندازی کنید

یک GenerativeModel را نمونه سازی کنید و نام مدل gemini-2.5-flash-image-preview مشخص کنید. بررسی کنید که responseModalities طوری پیکربندی کرده‌اید که شامل TEXT و IMAGE باشد.

کاتلین

val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "gemini-2.5-flash-image-preview",
    // Configure the model to respond with text and images (required)
    generationConfig = generationConfig {
        responseModalities = listOf(ResponseModality.TEXT,
        ResponseModality.IMAGE)
    }
)

جاوا

GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI()).generativeModel(
    "gemini-2.5-flash-image-preview",
    // Configure the model to respond with text and images (required)
    new GenerationConfig.Builder()
        .setResponseModalities(Arrays.asList(ResponseModality.TEXT, ResponseModality.IMAGE))
        .build()
);
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

تولید تصاویر (ورودی فقط متن)

می‌توانید با ارائه یک اعلان متنی، به مدل Gemini دستور دهید تا تصاویر را تولید کند:

کاتلین

// Provide a text prompt instructing the model to generate an image
val prompt = "A hyper realistic picture of a t-rex with a blue bag pack roaming a pre-historic forest."
// To generate image output, call `generateContent` with the text input
val generatedImageAsBitmap = model.generateContent(prompt)
.candidates.first().content.parts.filterIsInstance<ImagePart>()
.firstOrNull()?.image

جاوا

// Provide a text prompt instructing the model to generate an image
Content prompt = new Content.Builder()
    .addText("Generate an image of the Eiffel Tower with fireworks in the background.")
    .build();
// To generate an image, call `generateContent` with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        // iterate over all the parts in the first candidate in the result object
        for (Part part : result.getCandidates().get(0).getContent().getParts()) {
            if (part instanceof ImagePart) {
                ImagePart imagePart = (ImagePart) part;
                // The returned image as a bitmap
                Bitmap generatedImageAsBitmap = imagePart.getImage();
                break;
            }
        }
    }
    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

ویرایش تصاویر (ورودی متن و تصویر)

می‌توانید از یک مدل Gemini بخواهید که تصاویر موجود را با ارائه متن و یک یا چند تصویر در درخواست خود ویرایش کند:

کاتلین

// Provide an image for the model to edit
val bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.scones)
// Provide a text prompt instructing the model to edit the image
val prompt = content {
    image(bitmap)
    text("Edit this image to make it look like a cartoon")
}
// To edit the image, call `generateContent` with the prompt (image and text input)
val generatedImageAsBitmap = model.generateContent(prompt)
    .candidates.first().content.parts.filterIsInstance<ImagePart>().firstOrNull()?.image
// Handle the generated text and image

جاوا

// Provide an image for the model to edit
Bitmap bitmap = BitmapFactory.decodeResource(resources, R.drawable.scones);
// Provide a text prompt instructing the model to edit the image
Content promptcontent = new Content.Builder()
    .addImage(bitmap)
    .addText("Edit this image to make it look like a cartoon")
    .build();
// To edit the image, call `generateContent` with the prompt (image and text input)
ListenableFuture<GenerateContentResponse> response = model.generateContent(promptcontent);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        // iterate over all the parts in the first candidate in the result object
        for (Part part : result.getCandidates().get(0).getContent().getParts()) {
            if (part instanceof ImagePart) {
                ImagePart imagePart = (ImagePart) part;
                Bitmap generatedImageAsBitmap = imagePart.getImage();
                break;
            }
        }
    }
    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

تکرار و ویرایش تصاویر از طریق چت چند نوبتی

برای یک رویکرد مکالمه در ویرایش تصویر، می توانید از چت چند نوبتی استفاده کنید. این به درخواست‌های بعدی اجازه می‌دهد تا ویرایش‌ها را بدون نیاز به ارسال مجدد تصویر اصلی اصلاح کنند.

ابتدا یک چت را با startChat() راه اندازی کنید و به صورت اختیاری یک تاریخچه پیام ارائه دهید. سپس از sendMessage() برای پیام های بعدی استفاده کنید:

کاتلین

// Provide an image for the model to edit
val bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.scones)
// Create the initial prompt instructing the model to edit the image
val prompt = content {
    image(bitmap)
    text("Edit this image to make it look like a cartoon")
}
// Initialize the chat
val chat = model.startChat()
// To generate an initial response, send a user message with the image and text prompt
var response = chat.sendMessage(prompt)
// Inspect the returned image
var generatedImageAsBitmap = response
    .candidates.first().content.parts.filterIsInstance<ImagePart>().firstOrNull()?.image
// Follow up requests do not need to specify the image again
response = chat.sendMessage("But make it old-school line drawing style")
generatedImageAsBitmap = response
    .candidates.first().content.parts.filterIsInstance<ImagePart>().firstOrNull()?.image

جاوا

// Provide an image for the model to edit
Bitmap bitmap = BitmapFactory.decodeResource(resources, R.drawable.scones);
// Initialize the chat
ChatFutures chat = model.startChat();
// Create the initial prompt instructing the model to edit the image
Content prompt = new Content.Builder()
    .setRole("user")
    .addImage(bitmap)
    .addText("Edit this image to make it look like a cartoon")
    .build();
// To generate an initial response, send a user message with the image and text prompt
ListenableFuture<GenerateContentResponse> response = chat.sendMessage(prompt);
// Extract the image from the initial response
ListenableFuture<@Nullable Bitmap> initialRequest = Futures.transform(response,
    result -> {
        for (Part part : result.getCandidates().get(0).getContent().getParts()) {
            if (part instanceof ImagePart) {
                ImagePart imagePart = (ImagePart) part;
                return imagePart.getImage();
            }
        }
        return null;
    }, executor);
// Follow up requests do not need to specify the image again
ListenableFuture<GenerateContentResponse> modelResponseFuture = Futures.transformAsync(
    initialRequest,
    generatedImage -> {
        Content followUpPrompt = new Content.Builder()
            .addText("But make it old-school line drawing style")
            .build();
        return chat.sendMessage(followUpPrompt);
    }, executor);
// Add a final callback to check the reworked image
Futures.addCallback(modelResponseFuture, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        for (Part part : result.getCandidates().get(0).getContent().getParts()) {
            if (part instanceof ImagePart) {
                ImagePart imagePart = (ImagePart) part;
                Bitmap generatedImageAsBitmap = imagePart.getImage();
                break;
            }
        }
    }
    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

بهترین شیوه ها و محدودیت ها

  • فرمت خروجی : تصاویر به صورت PNG با ابعاد حداکثر 1024 پیکسل تولید می شوند.
  • انواع ورودی : این مدل از ورودی های صوتی یا تصویری برای تولید تصویر پشتیبانی نمی کند.
  • پشتیبانی از زبان : برای بهترین عملکرد، از زبان‌های زیر استفاده کنید: انگلیسی ( en )، اسپانیایی مکزیکی ( es-mx )، ژاپنی ( ja-jp )، چینی ساده شده ( zh-cn )، و هندی ( hi-in ).
  • مسائل مربوط به نسل :
    • تولید تصویر ممکن است همیشه فعال نشود، و گاهی اوقات منجر به خروجی فقط متن می شود. سعی کنید خروجی های تصویر را به طور صریح بخواهید (به عنوان مثال، "تصویر ایجاد کنید"، "تصاویر را در حین حرکت ارائه دهید"، "تصویر را به روز کنید").
    • ممکن است تولید مدل به صورت نیمه تمام متوقف شود. دوباره امتحان کنید یا درخواست دیگری را امتحان کنید .
    • مدل ممکن است متن را به صورت تصویر تولید کند. سعی کنید خروجی های متن را به طور صریح بخواهید (به عنوان مثال، "تولید متن روایی همراه با تصاویر").

برای جزئیات بیشتر به مستندات Firebase مراجعه کنید.

مراحل بعدی