گفتگو و متن

تولید محتوا (قالب Google)

قالب generateContent شرکت Google برای هر مدل گفتگو. Gemini CLI و SDKهای Google با آن به 1ai وصل می‌شوند، با استریم و فراخوانی تابع.

POST/v1beta/models/{model}:generateContent

این مسیر قالب generateContent شرکت Google را برای هر مدل گفتگوی 1ai می‌پذیرد. Gemini CLI با آن کار می‌کند. آدرس پایه https://1ai.ir است و مسیرها زیر /v1beta قرار دارند.

احراز هویت

کلید را در هدر x-goog-api-key بدهید. Authorization: Bearer و x-api-key هم پذیرفته می‌شوند. پارامتر ?key= هم کار می‌کند، ولی کلید در آدرس ممکن است در لاگ شبکه‌ها و CDNها بماند؛ هدر را ترجیح دهید.

نام مدل

در مسیر، نام مدل Gemini را بدون صاحب بنویسید: gemini-3.8-flash همان google/gemini-3.8-flash است. برای مدل دیگر نام کامل را بدهید، مثل /v1beta/models/openai/gpt-5.4-mini:generateContent . مسیر روی آخرین : تقسیم می‌شود.

استریم

برای استریم همان بدنه را به /v1beta/models/{model}:streamGenerateContent بفرستید. با ?alt=sse پاسخ رویدادهای SSE است (هر رویداد یک data:) و بدون آن یک آرایهٔ JSON است که همان‌طور که جلو می‌رود نوشته می‌شود. نمونهٔ استریم زیر از این مسیر استفاده می‌کند؛ در جدول نمونه‌ها فقط کد پایتون و Node آن مسیر را دارند. مسیر :countTokens هم هست و { "totalTokens": ... } برمی‌گرداند. رایگان است و در محدودیت نرخ حساب نمی‌شود.

ابزارها و تنظیمات

فقط ابزار functionDeclarations پذیرفته می‌شود. ابزارهای میزبانی‌شدهٔ Google (googleSearch، codeExecution، urlContext) با 400 tool_unsupported رد می‌شوند. در generationConfig این فیلدها اثر دارند: maxOutputTokens، temperature، topP، stopSequences، thinkingConfig.thinkingBudget، responseMimeType: "application/json" همراه responseSchema یا responseJsonSchema. فیلدهای candidateCount، responseModalities و speechConfig و cachedContent بدون خطا کنار گذاشته می‌شوند و همیشه یک کاندیدا می‌گیرید. thoughtSignature را در نوبت بعد همان‌طور که گرفتید پس بفرستید؛ فقط برای همان مدل معتبر است. خطاها قالب Google دارند: { "error": { "code": 400, "message": "...", "status": "INVALID_ARGUMENT" } }. هزینهٔ درخواست غیر استریم در هدر x-1ai-credits می‌آید.

نمونه‌ها

curl https://1ai.ir/v1beta/models/gemini-3.8-flash:generateContent \
  -H "x-goog-api-key: $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a concise assistant."
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "What is the capital of Japan?"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 100,
    "temperature": 0.2
  }
}'

200پاسخ

{
  "candidates": [
    {
      "index": 0,
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The capital of Japan is Tokyo."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 8,
    "totalTokenCount": 23
  },
  "modelVersion": "google/gemini-3.8-flash",
  "responseId": "5f2a8c1d9e3b4a7c8d0e6f1b3a2c4d95"
}

هدرها

x-goog-api-keystringالزامی
$کلید API شما. Authorization: Bearer و x-api-key هم پذیرفته می‌شوند.$

پارامترهای مسیر

modelstringالزامی
$نام مدل بدون صاحب برای Gemini (gemini-3.8-flash)، یا نام کامل برای مدل دیگر. پسوند :generateContent ، :streamGenerateContent یا :countTokens بخشی از مسیر است.$

پارامترهای کوئری

altstring
$فقط برای :streamGenerateContent : با sse پاسخ رویدادهای SSE است، وگرنه یک آرایهٔ JSON.$
keystring
$کلید API در آدرس؛ هدر x-goog-api-key امن‌تر است.$

بدنه‌ی درخواست

contentsarrayالزامی
$گفتگو تا اینجا، از 1 تا 8192 مورد.$
ویژگی‌های داخلی
- rolestring
  $user یا model .$
- partsarray
  $بخش‌های پیام: text ، inlineData (mimeType و data به base64)، fileData (fileUri)، functionCall و functionResponse .$
systemInstructionobject
$دستور سیستمی به شکل { "parts": [{ "text": "..." }] }. نام system_instruction هم پذیرفته می‌شود.$
toolsarray
$ابزارها، حداکثر 128 مورد. فقط functionDeclarations پذیرفته می‌شود.$
ویژگی‌های داخلی
- functionDeclarationsarray
  $آرایه‌ای از { name, description, parameters } که parameters طرح JSON با نوع‌های Gemini است.$
toolConfigobject
$تنظیم فراخوانی ابزار.$
ویژگی‌های داخلی
- functionCallingConfigobject
  ${ "mode": "AUTO" } ، ANY یا NONE .$
generationConfigobject
$تنظیم تولید.$
ویژگی‌های داخلی
- maxOutputTokensinteger
  $سقف توکن خروجی.$
- temperaturenumber
  $به مدل می‌رسد.$
- topPnumber
  $به مدل می‌رسد.$
- stopSequencesarray
  $رشته‌هایی که تولید را متوقف می‌کنند.$
- thinkingConfigobject
  ${ "thinkingBudget": 2048 } . بودجهٔ مثبت استدلال را روشن می‌کند: از 16,000 زیاد، از 4000 متوسط، پایین‌تر کم.$
- responseMimeTypestring
  $application/json برای خروجی JSON.$
- responseSchemaobject
  $طرح JSON خروجی، همراه responseMimeType . responseJsonSchema هم پذیرفته می‌شود.$

خطاها

INVALID_ARGUMENT400
بدنه نادرست است یا ابزار پشتیبانی‌نشده (googleSearch و مانند آن) فرستاده‌اید.
UNAUTHENTICATED401
کلید نادرست، غیرفعال یا منقضی است.
RESOURCE_EXHAUSTED402
اعتبار کافی نیست.
PERMISSION_DENIED403
این کلید اجازهٔ استفاده از این مدل را ندارد.
NOT_FOUND404
مدل یا متد وجود ندارد. متدهای پذیرفته: generateContent، streamGenerateContent، countTokens.
RESOURCE_EXHAUSTED429
به سقف نرخ رسیده‌اید.
UNAVAILABLE503
مدل موقتاً در دسترس نیست.

تولید محتوا (قالب Google)

احراز هویت

نام مدل

استریم

ابزارها و تنظیمات

نمونه‌ها

هدرها

پارامترهای مسیر

پارامترهای کوئری

بدنه‌ی درخواست

خطاها

صفحه‌های مرتبط