Gemini Developer API

للوصول إلى نموذجي Gemini Pro وFlash، ننصح مطوّري تطبيقات Android باستخدام Gemini Developer API من خلال Firebase AI Logic. يتيح لك هذا المنتج بدء الاستخدام بدون الحاجة إلى بطاقة ائتمان، كما يوفّر مستوى مجانيًا سخيًا. بعد إثبات صحة عملية الدمج مع قاعدة مستخدمين صغيرة، يمكنك توسيع نطاقها من خلال التبديل إلى الفئة المدفوعة.

صورة توضيحية لتطبيق Android يتضمّن حزمة تطوير البرامج (SDK) لنظام Android من Firebase يشير سهم من حزمة SDK إلى Firebase داخل بيئة السحابة الإلكترونية. من Firebase، يشير سهم آخر إلى Gemini Developer API، المرتبط بـ Gemini Pro & Flash، وكلاهما ضمن السحابة الإلكترونية.
الشكل 1. بنية دمج Firebase AI Logic للوصول إلى Gemini Developer API

خطوات البدء:

قبل التفاعل مع Gemini API مباشرةً من تطبيقك، عليك إجراء بعض الخطوات أولاً، بما في ذلك التعرّف على كيفية تقديم الطلبات وإعداد Firebase وتطبيقك لاستخدام حزمة SDK.

تجربة الطلبات

يمكن أن يساعدك اختبار الطلبات في العثور على أفضل صياغة ومحتوى وتنسيق لتطبيق Android. Google AI Studio هو بيئة تطوير متكاملة يمكنك استخدامها لإنشاء نماذج أولية وتصميم طلبات لحالات استخدام تطبيقك.

إنّ إنشاء الطلب المناسب لحالة الاستخدام هو فن أكثر من كونه علمًا، ما يجعل التجربة أمرًا بالغ الأهمية. يمكنك الاطّلاع على مزيد من المعلومات حول طلب الموافقة في مستندات Firebase.

بعد أن تصبح راضيًا عن الطلب، انقر على الزر "<>" للحصول على مقتطفات من الرمز يمكنك إضافتها إلى الرمز.

إعداد مشروع على Firebase وربط تطبيقك به

بعد أن تصبح جاهزًا لاستدعاء واجهة برمجة التطبيقات من تطبيقك، اتّبِع التعليمات الواردة في "الخطوة 1" من دليل بدء استخدام Firebase AI Logic لإعداد Firebase وحزمة تطوير البرامج (SDK) في تطبيقك.

إضافة تبعية Gradle

أضِف اعتمادية Gradle التالية إلى وحدة تطبيقك:

Kotlin

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")
}

Java

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 وتحديد اسم النموذج:

Kotlin

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

Java

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() مع طلبك.

Kotlin

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

Java

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:

Kotlin

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

Java

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:

Kotlin

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)
    }
}

Java

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:

Kotlin

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)
  }
}

Java

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() لإرسال رسائل المحادثة.

Kotlin

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?")
}

Java

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 (المعروف أيضًا باسم Nano Banana) إنشاء الصور وتعديلها بالاستفادة من المعرفة العالمية والاستدلال المنطقي. وينتج صورًا ذات صلة بالسياق، مع دمج أو تداخل سلس بين النص والصور. يمكنه أيضًا إنشاء صور دقيقة تتضمّن تسلسلات نصية طويلة، ويتيح تعديل الصور بأسلوب حواري مع الحفاظ على السياق.

كبديل عن Gemini، يمكنك استخدام نماذج Imagen، خاصةً لإنشاء صور عالية الجودة تتطلّب محاكاة الواقع أو تفاصيل فنية أو أنماطًا معيّنة. ومع ذلك، سيكون Gemini أكثر من كافٍ لمعظم حالات الاستخدام من جهة العميل لتطبيقات Android.

يوضّح هذا الدليل كيفية استخدام نموذج Gemini 2.5 Flash Image باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic لنظام التشغيل Android. لمزيد من التفاصيل حول إنشاء الصور باستخدام Gemini، اطّلِع على مستندات إنشاء الصور باستخدام Gemini على Firebase. إذا كنت مهتمًا باستخدام نماذج Imagen، يمكنك الاطّلاع على المستندات.

‫Google AI Studio يعرض إمكانات إنشاء الصور.
الشكل 1. استخدام Google AI Studio لتحسين طلبات إنشاء الصور

تهيئة النموذج التوليدي

أنشئ مثيلاً من GenerativeModel وحدِّد اسم النموذج gemini-2.5-flash-image-preview. تأكَّد من ضبط responseModalities لتضمين كل من TEXT وIMAGE.

Kotlin

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)
    }
)

Java

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 لإنشاء صور من خلال تقديم طلب نصي فقط:

Kotlin

// 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

Java

// 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 تعديل صور حالية من خلال تقديم نص وصورة واحدة أو أكثر في طلبك:

Kotlin

// 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

Java

// 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() للرسائل اللاحقة:

Kotlin

// 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

Java

// 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 لمزيد من التفاصيل.

الخطوات التالية