Gemini الأصلي

إنشاء المحتوى

ينشئ محتوى باستخدام تنسيق Google Gemini API

POST
/v1beta/models/{model}:generateContent

استخدم تنسيقات الطلب والاستجابة الخاصة بـ Gemini مع نموذج يتم إرجاعه بواسطة قائمة النماذج. يتم قبول تنسيق ProtoJSON بتنسيق lowerCamelCase وأسماء حقول proto بتنسيق snake_case المقابل. تعتمد الحقول والقيم الاختيارية المدعومة على النموذج المختار.

معاملات المسار (Path Parameters)

modelstringpathمطلوب

اسم النموذج (على سبيل المثال، gemini-2.5-pro، gemini-3.5-flash).

معاملات الاستعلام (Query Parameters)

keystringquery

مفتاح API (بديل للمصادقة عبر الترويسة).

المصادقة (Authentication)

تدعم نقاط نهاية Gemini طرق مصادقة متعددة:

  • معامل الاستعلام ?key=YOUR_API_KEY
  • ترويسة x-goog-api-key: YOUR_API_KEY
  • ترويسة Authorization: Bearer YOUR_API_KEY

نص الطلب (Request Body)

contentsarrayمطلوب

محتويات المحادثة مع parts و role اختياري. تستخدم أجزاء الوسائط inlineData / inline_data أو fileData / file_data. لا يمكن استخدام الملفات و Cache IDs التي تم إنشاؤها بواسطة TokenLab إلا في مساحة العمل الخاصة بها.

systemInstructionobject

تعليمات النظام للنموذج.

generationConfigobject

إعدادات الإنشاء مثل temperature و topP و topK و maxOutputTokens و stopSequences و candidateCount و responseModalities و responseMimeType و responseSchema و thinkingConfig. يتم أيضاً قبول أسماء snake_case المقابلة. تعتمد القيم والمجموعات المدعومة على النموذج.

safetySettingsarray

إعدادات مرشح الأمان.

toolsarray

أدوات Gemini مثل functionDeclarations. تعتمد أنواع الأدوات المدعومة على النموذج.

toolConfigobject

تكوين الأداة مثل functionCallingConfig.

cachedContentstring

اسم المحتوى المخزن مؤقتاً الذي تم إنشاؤه باستخدام إنشاء محتوى مخزن مؤقتاً، على سبيل المثال cachedContents/abc123. يعمل فقط في مساحة العمل التي أنشأته.

يمكن لكل حقل بتنسيق lowerCamelCase الموضح أعلاه استخدام تهجئة proto الرسمية بتنسيق snake_case أيضاً، على سبيل المثال system_instruction و generation_config و safety_settings و tool_config و cached_content و file_data.file_uri و inline_data.mime_type.

الطرق المدعومة (Supported Methods)

يتضمن API المتوافق مع Gemini كلاً من قائمة النماذج، و الحصول على نموذج، و generateContent، و streamGenerateContent، و countTokens، والملفات، والمحتوى المخزن مؤقتاً. ميزات Gemini Interactions و Live غير متاحة.

اقرأ استجابة الحصول على نموذج الخاصة بالنموذج قبل استدعائه: تدرج supportedGenerationMethods الإجراءات التي يقبلها ذلك النموذج.

الاستجابة (Response)

candidatesarray

مرشحات المحتوى الذي تم إنشاؤه.

usageMetadataobject

معلومات استخدام الرموز (Tokens).

الطلب

curl -X POST "https://api.tokenlab.sh/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

الأخطاء (Errors)

  • 400 INVALID_ARGUMENT: نص الطلب غير صالح، أو النموذج لا يقبل طلبات Gemini.
  • 401 UNAUTHENTICATED: مفتاح API مفقود أو غير صالح.
  • 402 RESOURCE_EXHAUSTED: الرصيد منخفض جداً لهذا الطلب.
  • 503 UNAVAILABLE: لا يوجد مسار متاح للنموذج في الوقت الحالي. حاول مرة أخرى لاحقاً.

إدخال الوسائط (Media Input)

ضع الوسائط داخل contents[].parts[] كبايتات Base64 مضمنة (inlineData أو inline_data) أو كرابط https عام (fileData أو file_data). يتم دعم الصور والصوت والفيديو.

الصورة (Image)

استخدم بايتات الصور المضمنة:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

استخدم رابط صورة:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}

الصوت (Audio)

استخدم رابط صوت، هنا مع أسماء proto بتنسيق snake_case:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Transcribe and summarize this audio." },
        {
          "file_data": {
            "mime_type": "audio/mpeg",
            "file_uri": "https://example.com/sample.mp3"
          }
        }
      ]
    }
  ]
}

الفيديو (Video)

استخدم رابط فيديو:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Describe this video briefly." },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/sample.mp4"
          }
        }
      ]
    }
  ]
}

الاستجابة

Response
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Hello! How can I assist you today?"}
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"}
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 10,
    "totalTokenCount": 15
  }
}

حساب الرموز (Tokens) والتضمينات (Embeddings)

حساب الرموز (POST /v1beta/models/{model}:countTokens) يتطلب مفتاح API ولا تتم محاسبته. استخدم العدد للتخطيط؛ يتم احتساب تكلفة طلب الإنشاء من usageMetadata في تلك الاستجابة.

تستخدم نماذج التضمين إنشاء تضمين (POST /v1/embeddings). قم باستدعاء embedContent أو batchEmbedContents فقط لنموذج تدرج استجابة الحصول على نموذج الخاصة به هذه الطرق في supportedGenerationMethods.

التفويض

AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

معاملات المسار

model*string

اسم النموذج (مثال: gemini-2.5-pro)

معاملات الاستعلام

key?string

مفتاح API (بديل لمصادقة الرأس)

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"

جسم الطلب

application/json

طلب Gemini GenerateContent الأصلي. يتم قبول والحفاظ على كل من أسماء ProtoJSON بصيغة lowerCamelCase وأسماء proto الأصلية بصيغة snake_case، بما في ذلك الطلبات المختلطة. إذا كان كلا تهجئتي الحقل موجودتين، فإن TokenLab لا تقوم بدمجهما أو اختيار أولوية محلية. يتم إعادة توجيه الحقول غير المعروفة على أساس بذل أفضل جهد.

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json