نظرة عامة على Gemini API

تتيح لك واجهة برمجة تطبيقات Gemini إمكانية الوصول إلى أحدث النماذج التوليدية من Google. وعندما تتعرف على الميزات العامة المتاحة لك من خلال واجهة برمجة التطبيقات، يمكنك تجربة برنامج تعليمي للغتك التي تختارها لبدء التطوير.

النماذج

Gemini هو سلسلة من نماذج الذكاء الاصطناعي التوليدي متعددة الوسائط التي طوّرتها Google. يمكن لنماذج Gemini قبول النصوص والصور في الطلبات، استنادًا إلى شكل النموذج الذي تختاره والردود النصية الناتجة.

للحصول على معلومات أكثر تفصيلاً حول النموذج، يُرجى الرجوع إلى صفحة نماذج Gemini. يمكنك أيضًا استخدام طريقة list_models لإدراج جميع النماذج المتاحة ثم طريقة get_model للحصول على البيانات الوصفية لنموذج معيّن.

تقديم البيانات والتصميم

تقبل نماذج Gemini المحدّدة البيانات النصية وملفات الوسائط كإدخال. تخلق هذه القدرة العديد من الاحتمالات الإضافية لإنشاء المحتوى وتحليل البيانات وحل المشكلات. هناك بعض القيود والمتطلبات التي يجب مراعاتها، بما في ذلك الحد العام للرمز المميز للإدخال الخاص بالنموذج الذي تستخدمه. للحصول على معلومات حول حدود الرموز المميّزة لطُرز معيّنة، يُرجى الاطّلاع على طُرز Gemini.

لا يمكن أن يتجاوز حجم الطلبات التي تستخدم Gemini API حجم 20 ميغابايت. توفّر واجهة برمجة التطبيقات Gemini واجهة برمجة تطبيقات (File API) لتخزين ملفات الوسائط مؤقتًا لاستخدامها في إرسال الطلبات، ما يتيح لك تقديم بيانات طلب تتجاوز الحدّ الأقصى المسموح به وهو 20 ميغابايت. لمزيد من المعلومات حول استخدام Files API وتنسيقات الملفات المتوافقة مع إرسال الطلبات، يمكنك الاطّلاع على المقالة طلب استخدام ملفات الوسائط.

تصميم الطلب وإدخال النص

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

إنشاء محتوى

تتيح لك واجهة Gemini API استخدام كلّ من بيانات النصوص والصور لتقديم الطلبات، وذلك استنادًا إلى شكل النموذج الذي تستخدمه. على سبيل المثال، يمكنك إنشاء نص من الطلبات النصية فقط أو من الطلبات المتعدّدة الوسائط باستخدام نموذج Gemini 1.5. يقدم هذا القسم أمثلة تعليمة برمجية أساسية لكل منها. يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات generateContent للاطّلاع على مثال أكثر تفصيلاً يشمل جميع المَعلمات.

إدخال النصوص والصور

يمكنك إرسال طلب نصي يحتوي على صورة إلى طراز Gemini 1.5 لتنفيذ مهمة ذات صلة بالرؤية. على سبيل المثال، إضافة تسميات توضيحية إلى صورة أو تحديد ما يوجد في صورة.

توضح أمثلة التعليمات البرمجية التالية التنفيذ الأساسي لمطالبة نصية وصورة لكل لغة مدعومة:

Python

model = genai.GenerativeModel('gemini-1.5-flash')

cookie_picture = {
    'mime_type': 'image/png',
    'data': pathlib.Path('cookie.png').read_bytes()
}
prompt = "Do these look store-bought or homemade?"

response = model.generate_content(
    model="gemini-1.5-flash",
    content=[prompt, cookie_picture]
)
print(response.text)

يمكنك الاطّلاع على دليل Python التعليمي للاطّلاع على مقتطف الرمز الكامل.

البدء

vmodel := client.GenerativeModel("gemini-1.5-flash")

data, err := os.ReadFile(filepath.Join("path-to-image", imageFile))
if err != nil {
  log.Fatal(err)
}
resp, err := vmodel.GenerateContent(ctx, genai.Text("Do these look store-bought or homemade?"), genai.ImageData("jpeg", data))
if err != nil {
  log.Fatal(err)
}

للاطّلاع على مثال كامل، يُرجى الاطّلاع على البرنامج التعليمي Go.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Do these look store-bought or homemade?";
const image = {
  inlineData: {
    data: Buffer.from(fs.readFileSync("cookie.png")).toString("base64"),
    mimeType: "image/png",
  },
};

const result = await model.generateContent([prompt, image]);
console.log(result.response.text());

يمكنك الاطّلاع على برنامج Node.js التعليمي للاطّلاع على مثال كامل.

الويب

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Do these look store-bought or homemade?";
const image = {
  inlineData: {
    data: base64EncodedImage /* see JavaScript quickstart for details */,
    mimeType: "image/png",
  },
};

const result = await model.generateContent([prompt, image]);
console.log(result.response.text());

راجِع البرنامج التعليمي على الويب للاطّلاع على مثال كامل.

Dart (Flutter)

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Do these look store-bought or homemade?';
final imageBytes = await File('cookie.png').readAsBytes();
final content = [
  Content.multi([
    TextPart(prompt),
    DataPart('image/png', imageBytes),
  ])
];

final response = await model.generateContent(content);
print(response.text);

للاطّلاع على مثال كامل، يمكنك الاطّلاع على البرنامج التعليمي حول لعبةDart (Flutter).

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let cookieImage = UIImage(...)
let prompt = "Do these look store-bought or homemade?"

let response = try await model.generateContent(prompt, cookieImage)

يمكنك الاطّلاع على دليل Swift التعليمي للاطّلاع على مثال كامل.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val cookieImage: Bitmap = // ...
val inputContent = content() {
  image(cookieImage)
  text("Do these look store-bought or homemade?")
}

val response = generativeModel.generateContent(inputContent)
print(response.text)

راجع برنامج Android التعليمي للحصول على مثال كامل.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=${API_KEY} \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @<(echo'{
          "contents":[
            { "parts":[
                {"text": "Do these look store-bought or homemade?"},
                { "inlineData": {
                    "mimeType": "image/png",
                    "data": "'$(base64 -w0 cookie.png)'"
                  }
                }
              ]
            }
          ]
         }')

يمكنك الاطّلاع على البرنامج التعليمي ReST API للحصول على مزيد من التفاصيل.

إدخال النص فقط

يمكن لواجهة Gemini API أيضًا معالجة إدخال النص فقط. تتيح لك هذه الميزة تنفيذ مهام معالجة اللغات الطبيعية (NLP) مثل إكمال النص وتلخيصه.

توضّح أمثلة الرمز البرمجي التالية التنفيذ الأساسي لمطالبة نصية فقط لكل لغة متاحة:

Python

model = genai.GenerativeModel('gemini-1.5-flash')

prompt = "Write a story about a magic backpack."

response = model.generate_content(prompt)

يمكنك الاطّلاع على برنامج Python التعليمي للحصول على المثال الكامل.

البدء

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

للاطّلاع على مثال كامل، يُرجى الاطّلاع على البرنامج التعليمي Go.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContent(prompt);
console.log(result.response.text());

يمكنك الاطّلاع على برنامج Node.js التعليمي للاطّلاع على مثال كامل.

الويب

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContent(prompt);
console.log(result.response.text());

راجِع البرنامج التعليمي على الويب للاطّلاع على مثال كامل.

Dart (Flutter)

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Write a story about a magic backpack.';
final content = [Content.text(prompt)];
final response = await model.generateContent(content);
print(response.text);

للاطّلاع على مثال كامل، يمكنك الاطّلاع على البرنامج التعليمي حول لعبةDart (Flutter).

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let prompt = "Write a story about a magic backpack."

let response = try await model.generateContent(prompt)

يمكنك الاطّلاع على دليل Swift التعليمي للاطّلاع على مثال كامل.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val prompt = "Write a story about a magic backpack."
val response = generativeModel.generateContent(prompt)
print(response.text)

راجع برنامج Android التعليمي للحصول على مثال كامل.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{ "contents":[
      { "parts":[{"text": "Write a story about a magic backpack"}]}
    ]
}'

يمكنك الاطّلاع على البرنامج التعليمي ReST API للحصول على مزيد من التفاصيل.

المحادثات المتعددة الأدوار (الدردشة)

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

توضح أمثلة التعليمات البرمجية التالية التنفيذ الأساسي لتفاعل الدردشة لكل لغة معتمدة:

Python

  model = genai.GenerativeModel('gemini-1.5-flash')
  chat = model.start_chat(history=[])

  response = chat.send_message(
      "Pretend you\'re a snowman and stay in character for each response.")
  print(response.text)

  response = chat.send_message(
      "What\'s your favorite season of the year?")
  print(response.text)

اطّلع على العرض التوضيحي للدردشة في برنامج Python التعليمي للحصول على مثال كامل.

البدء

model := client.GenerativeModel("gemini-1.5-flash")
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Pretend you're a snowman and stay in character for each response."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello! It's cold! Isn't that great?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("What's your favorite season of the year?"))
if err != nil {
  log.Fatal(err)
}

يمكنك مشاهدة العرض التوضيحي للدردشة في البرنامج التعليمي Go للاطّلاع على مثال كامل.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: "Pretend you're a snowman and stay in character for each response.",
    },
    {
      role: "model",
      parts: "Hello! It's cold! Isn't that great?",
    },
  ],
  generationConfig: {
    maxOutputTokens: 100,
  },
});

const msg = "What's your favorite season of the year?";
const result = await chat.sendMessage(msg);
console.log(result.response.text());

يمكنك الاطّلاع على العرض التوضيحي للدردشة في البرنامج التعليمي Node.js للاطّلاع على مثال كامل.

الويب

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: "Pretend you're a snowman and stay in character for each response.",
    },
    {
      role: "model",
      parts: "Hello! It's so cold! Isn't that great?",
    },
  ],
  generationConfig: {
    maxOutputTokens: 100,
  },
});

const msg = "What's your favorite season of the year?";
const result = await chat.sendMessage(msg);
console.log(result.response.text());

يُرجى الاطّلاع على العرض التوضيحي الخاص بالمحادثات في البرنامج التعليمي على الويب للاطّلاع على مثال كامل.

Dart (Flutter)

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final chat = model.startChat(history: [
  Content.text(
      "Pretend you're a snowman and stay in character for each response."),
  Content.model([TextPart("Hello! It's cold! Isn't that great?")]),
]);
final content = Content.text("What's your favorite season of the year?");
final response = await chat.sendMessage(content);
print(response.text);

للاطّلاع على مثال كامل، يمكنك مشاهدة العرض التوضيحي للدردشة في الدليل التعليمي حول لعبةDart (Flutter).

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let chat = model.startChat()

var message = "Pretend you're a snowman and stay in character for each response."
var response = try await chat.sendMessage(message)

message = "What\'s your favorite season of the year?"
response = try await chat.sendMessage(message)

راجِع العرض التوضيحي للدردشة في برنامج Swift التعليمي للاطّلاع على مثال كامل.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val chat = generativeModel.startChat()
val response = chat.sendMessage("Pretend you're a snowman and stay in
        character for each response.")
print(response.text)

راجع برنامج Android التعليمي للحصول على مثال كامل.

cURL

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Pretend you're a snowman and stay in character for each
        {"role": "model",
            response."}]},
         "parts":[{
           "text": "Hello! It's so cold! Isn't that great?"}]},
        {"role": "user",
         "parts":[{
           "text": "What\'s your favorite season of the year?"}]},
       ]
    }' 2> /dev/null | grep "text"
# response example:
"text": "Winter, of course!"

يمكنك الاطّلاع على البرنامج التعليمي ReST API للحصول على مزيد من التفاصيل.

الردود التي تم بثها

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

الردود التي يتم بثها هي خيار للطلبات الحرة والمحادثات باستخدام نماذج Gemini. توضح أمثلة التعليمات البرمجية التالية كيفية طلب استجابة مباشرة لمطالبة لكل لغة مدعومة:

Python

prompt = "Write a story about a magic backpack."

response = genai.stream_generate_content(
    model="models/gemini-1.5-flash",
    prompt=prompt
)

يمكنك الاطّلاع على دليل Python التعليمي للاطّلاع على مقتطف الرمز الكامل.

البدء

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-1.5-flash")

iter := model.GenerateContentStream(ctx, genai.Text("Write a story about a magic backpack."))
for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // print resp
}

للاطّلاع على مثال كامل، يُرجى الاطّلاع على البرنامج التعليمي Go.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream([prompt]);
// print text as it comes in
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
}

يمكنك الاطّلاع على برنامج Node.js التعليمي للاطّلاع على مثال كامل.

الويب

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream([prompt]);
// print text as it comes in
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
}

راجِع البرنامج التعليمي على الويب للاطّلاع على مثال كامل.

Dart (Flutter)

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Write a story about a magic backpack.';
final content = [Content.text(prompt)];
final response = model.generateContentStream(content);
await for (final chunk in response) {
  print(chunk.text);
}

للاطّلاع على مثال كامل، يمكنك الاطّلاع على البرنامج التعليمي حول لعبةDart (Flutter).

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let prompt = "Write a story about a magic backpack."

let stream = model.generateContentStream(prompt)
for try await chunk in stream {
  print(chunk.text ?? "No content")
}

يمكنك الاطّلاع على دليل Swift التعليمي للاطّلاع على مثال كامل.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val inputContent = content {
  text("Write a story about a magic backpack.")
}

var fullResponse = ""
generativeModel.generateContentStream(inputContent).collect { chunk ->
  print(chunk.text)
  fullResponse += chunk.text
}

راجع برنامج Android التعليمي للحصول على مثال كامل.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:streamGenerateContent?key=${API_KEY} \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{ "contents":[
            {"role": "user",
              "parts":[{"text": "Write a story about a magic backpack."}]
            }
          ]
        }' > response.json

يمكنك الاطّلاع على البرنامج التعليمي ReST API للحصول على مزيد من التفاصيل.

الردود بتنسيق JSON

بناءً على طلبك، قد تريد أن يتم عرض الردّ على الطلب بتنسيق بيانات منظَّمة، لا سيما إذا كنت تستخدم الردود لتعبئة واجهات البرمجة. توفّر واجهة برمجة التطبيقات Gemini API مَعلمة إعداد لطلب استجابة بتنسيق JSON.

يمكنك الحصول على نتيجة نموذج JSON من خلال ضبط خيار ضبط response_mime_type على application/json، وفي رسالة الطلب، يُرجى وصف تنسيق JSON الذي تريده للاستجابة:

Python

model = genai.GenerativeModel('gemini-1.5-flash',
                              generation_config={"response_mime_type": "application/json"})

prompt = """
  List 5 popular cookie recipes.

  Using this JSON schema:

    Recipe = {"recipe_name": str}

  Return a `list[Recipe]`
  """

response = model.generate_content(prompt)
print(response.text)

cURL

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "\nList 5 popular cookie recipes.\n\nUsing this JSON schema:\n\n  Recipe = {\"recipe_name\": str}\n\nReturn a `list[Recipe]`\n      "
            }
          ]
        }
      ]
      "generationConfig": {
            "response_mime_type": "application/json",
      }
    }'

وعلى الرغم من أنّ طُرز Gemini 1.5 Flash لا تقبل سوى وصف نص لمخطط JSON الذي تريد عرضه، تتيح لك نماذج Gemini 1.5 Pro تمرير كائن مخطط (أو ما يعادله من نوع Python)، وسيتّبع ناتج النموذج هذا المخطط بدقة. ويُعرف ذلك أيضًا باسم الإنشاء الخاضع للرقابة أو فك الترميز المحدود.

على سبيل المثال، للحصول على قائمة بكائنات Recipe، مرِّر list[Recipe] إلى الحقل response_schema في الوسيطة generation_config:

Python

import typing_extensions as typing

class Recipe(typing.TypedDict):
  recipe_name: str

model = genai.GenerativeModel(model_name="models/gemini-1.5-pro")

result = model.generate_content(
  "List 5 popular cookie recipes",
  generation_config=genai.GenerationConfig(response_mime_type="application/json",
                                           response_schema = list[Recipe]))

print(result.text)

cURL

  curl https://generativelanguage.googleapis.com/v1beta/models/models/gemini-1.5-pro:generateContent?
      -H 'Content-Type: application/json'
      -X POST \
      -d '{
        "contents": [
          {
            "parts": [
              {
                "text": "List 5 popular cookie recipes"
              }
            ]
          }
        ],
        "generationConfig": {
          "responseMimeType": "application/json",
          "responseSchema": {
            "type": "ARRAY",
            "items": {
              "type": "OBJECT",
              "properties": {
                "recipe_name": {
                  "type": "STRING"
                }
              }
            }
          }
        }
      }'
  ```

لمزيد من المعلومات، راجِع البدء السريع لوضع JSON في كتاب الطهي الخاص بواجهة برمجة تطبيقات Gemini.

مواد العرض المضمّنة

تنشئ خدمة التضمين في واجهة برمجة تطبيقات Gemini عمليات تضمين حديثة للكلمات والعبارات والجُمل. ويمكن بعد ذلك استخدام التضمينات الناتجة في مهام برنامج NLP، مثل البحث الدلالي، وتصنيف النص، والتجميع العنقودي، بالإضافة إلى العديد من المهام الأخرى. يمكنك الاطّلاع على دليل عمليات التضمين لمعرفة ماهية التضمينات وبعض حالات الاستخدام الرئيسية لخدمة التضمين لمساعدتك على البدء.

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