داشبورد توسعه‌دهنده
پرسش از هوش مصنوعی
پرسش از هوش مصنوعی

راهنمای API مدل‌های Google Gemini ​

AvalAI مدل‌های Google Gemini را با یک کلید API و چند قالب درخواست ارائه می‌کند. برای کدنویسی، گردش‌کارهای عامل‌ها و کار دانشی چندوجهی با خروجی متنی، gemini-4-hydrogen را انتخاب کنید؛ برای داوری نوع‌دار بر شواهد مشترک، از gemini-decision-1 استفاده کنید. مثال‌های موجود Gemini 3.7 Flash در ادامه حفظ شده‌اند؛ کنترل‌ها و محدودیت‌های همان مدل دقیقی را دنبال کنید که انتخاب می‌کنید.

Gemini 4 Hydrogen ​

از gemini-4-hydrogen برای کدنویسی روزمره، گردش‌کارهای عامل‌ها و کار دانشی چندوجهی که پاسخ متنی لازم دارد استفاده کنید. این مدل از سطح 0 در AvalAI، از طریق Gemini بومی، Chat Completions، Responses و Messages در دسترس است. بدنه کامل نقطه پایانی انتخابی را به کار ببرید؛ قالب‌های آن‌ها متفاوت‌اند.

ویژگیHydrogen
مسیر تولید بومی/v1beta/models/gemini-4-hydrogen:generateContent
مسیرهای سازگار/v1/chat/completions، /v1/responses، /v1/messages
قرارداد زمینه Google1,048,576 توکن مشترک میان ورودی، تفکر و خروجی
سقف خروجی همگام65,536 توکن با احتساب تفکر
سطح‌های تفکر در بالادستlow، medium، high، xhigh؛ پیش‌فرض high
ورودی / ورودی از حافظه نهان / خروجی AvalAI$1.50 / $0.075 / $7.50 برای هر میلیون توکن
حافظه نهانفقط ضمنی؛ بدون ایجاد صریح حافظه نهان یا ارجاع به محتوای نهان‌شده

Google ورودی متن، تصویر، صدا، ویدئو و PDF با خروجی متنی را معرفی می‌کند. قالب انتقال مستند مسیر واقعی خود را انتخاب و جداگانه ارزیابی کنید؛ درخواست پایه تازه این راهنما متنی است. گردش‌کارهای رمزگشایی طولانی Google از تولید همگام جدا هستند. پنجره مشترک، خروجی همگام یک‌میلیون‌توکنی یا اجرای پس‌زمینه AvalAI را ثابت نمی‌کند. برای تفکر و پاسخ، فضای خروجی در نظر بگیرید.

با رفتار پیش‌فرض تفکر شروع کنید و کنترل نمونه‌گیری را ارسال نکنید. Google در Hydrogen مقدارهای معتبر temperature، top_p/topP و top_k/topK را نادیده می‌گیرد و مقدارهای خارج از بازه را رد می‌کند. آستانه حافظه نهان ضمنی در بالادست ۴٬۰۹۶ توکن ورودی است؛ استفاده موفق و واجد شرایط از آن، نرخ ورودی از حافظه نهان جدول را دارد. طولانی‌بودن و تکرار پرامپت، استفاده موفق از حافظه نهان را ثابت نمی‌کند. مصرف واقعی و هزینه صورتحساب را بخوانید. Hydrogen متن بازمی‌گرداند و در بالادست از تولید تصویر و صدا یا Live API پشتیبانی نمی‌کند. ابزارهای میزبانی‌شده به پشتیبانی مسیر AvalAI و اعتبارسنجی جداگانه نیاز دارند؛ چهار مسیر تولید به‌تنهایی این پشتیبانی را ثابت نمی‌کنند.

درخواست پایه بومی Hydrogen ​

این درخواست کوچک از قالب بومی و مسیر تأییدشده AvalAI پیروی می‌کند. درخواست در برابر API زنده AvalAI اجرا نشده است. برای پاسخ‌های آموزشی متناظر و نمونه‌های نقاط پایانی سازگار، خبر انتشار را ببینید.

bash
curl --fail-with-body --connect-timeout 10 --max-time 30 \
  https://api.avalai.ir/v1beta/models/gemini-4-hydrogen:generateContent \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Explain a token bucket rate limiter in three sentences."}]
      }
    ]
  }'

نشانی پایه SDK را برای Gemini بومی برابر https://api.avalai.ir و برای SDK شرکت OpenAI برابر https://api.avalai.ir/v1 قرار دهید. Messages بومی قواعد احراز هویت و بدنه خودش را دارد. صفحه ارائه‌دهنده Google و مرجع v1beta مرزهای هر مدل را توضیح می‌دهند.

Gemini Decision 1: قالب تصمیم‌گیری را انتخاب کنید ​

زمانی از gemini-decision-1 استفاده کنید که فضای پاسخ از پیش تعریف شده است: برقراربودن یک شرط را بسنجید، صف پشتیبانی یا برچسب ابزار را انتخاب کنید، یا شواهد را بر معیارهای ترتیب‌دار امتیاز دهید. این مدل از سطح 0 در AvalAI در دسترس است. داوری‌های نوع‌دار را بدون تولید توکن خروجی ارائه می‌کند؛ پاسخ متنی یا آرگومان ابزار نمی‌نویسد و اقدام انتخابی را اجرا نمی‌کند.

مسیرشواهد مشترکپرسش‌ها و نوع دودوییپاسخ
Decisions استاندارد /v1/decisionsinputآرایه؛ شناسه هر پرسش در name؛ نوع دودویی predicateآرایه پاسخ؛ usage.input_tokens / output_tokens
System One /v1/systemonestateنگاشت با کلید شناسه پرسش؛ نوع دودویی noul؛ criteria.true و false اختیارینگاشت پاسخ؛ usage.input_tokens / output_tokens
Decisions بومی Google /v1beta/decisionsinputنگاشت با کلید شناسه پرسش؛ نوع دودویی noul؛ criteria.true_description و false_description اختیارینگاشت پاسخ؛ usage.total_input_tokens / total_output_tokens

Choice استاندارد از choices و Score استاندارد از levels استفاده می‌کند؛ هر دو قالب بومی criteria می‌گیرند: نگاشت گزینه برای Choice و آرایه ترتیب‌دار توضیح‌ها برای Score. تغییر URL به‌تنهایی، ساختار نادرست را اصلاح نمی‌کند. با درخواست متنی و پاسخ آموزشی کامل مرجع انتخابی شروع کنید. برای ورودی بومی Google، رکورد ساختاریافته دلخواه را به متن مشترک تبدیل کنید؛ مثال‌های وضعیت شیئی Jev، تضمین انتقال همان قالب برای Gemini نیستند.

پنجره مدل Google برای مجموع ورودی مشترک و همه پرسش‌ها ۲۶۲٬۱۴۴ توکن است. API بومی آن حداکثر ۱٬۰۰۰ پرسش مستقل می‌پذیرد؛ این محدودیت بالادستی است، نه ظرفیت اندازه‌گیری‌شده AvalAI یا جایگزین قراردادهای جداگانه OpenAI و Clef. هزینه هر میلیون توکن ورودی در همه نوع‌های ورودی $0.10 است. شواهد مشترک یک‌بار محاسبه می‌شوند؛ هر پرسش، توکن دستور، معیار و قالب‌بندی اضافه می‌کند. نرخ خروجی و ورودی از حافظه نهان در فهرست $0.00 است، اما حافظه نهان پشتیبانی نمی‌شود و درخواست همچنان هزینه ورودی دارد.

Google قابلیت‌های متن، تصویر، ویدئو، صدا و PDF را معرفی می‌کند. این انتشار با متن مشترک شروع می‌شود، زیرا بلوک‌های PDF و سند، کنترل وضوح، حفظ دقیق متن چندقطعه‌ای، رسانه راه‌دور و انتقال Files API از طریق AvalAI تأیید نشده‌اند. قابلیت بالادستی، مسیر انتقال تأییدشده نیست. بررسی‌های پیشین Jev، پاسخ زنده یا اندازه‌گیری کیفیت تصمیم‌گیری این شناسه تازه را ارائه نمی‌کنند. داوری مدل را با نمونه‌های برچسب‌خورده ارزیابی کنید، فیلدهای غایب را حفظ کنید، موارد نامطمئن را به بازبینی بفرستید و بررسی مجوز و اجرای اقدام را در کد قطعی برنامه نگه دارید. برای سیاست یکپارچه‌سازی، راهنمای مدل‌های تصمیم‌گیری را ببینید.

نمای کلی Gemini 3.7 Flash ​

ویژگیجزئیات
شناسه مدلgemini-3.7-flash
زمینه ورودی۱٬۰۴۸٬۵۷۶ توکن
حداکثر خروجی۶۵٬۵۳۶ توکن
ورودی‌هامتن، تصویر، ویدیو، صدا، PDF
خروجیمتن
نقاط پایانیv1beta/، v1/chat/completions، v1/messages و پشتیبانی جزئی v1/responses
قیمت تشویقی$0.75 ورودی، $0.075 ورودی کش‌شده و $3.75 خروجی به ازای ۱ میلیون توکن تا ۳۱ دسامبر ۲۰۲۶
قیمت استاندارد$1.50 ورودی، $0.15 ورودی کش‌شده و $7.50 خروجی به ازای ۱ میلیون توکن پس از ۳۱ دسامبر ۲۰۲۶

انتخاب قالب API ​

  • برای برنامه‌های سازگار با OpenAI و بیشترین سازگاری مهاجرت از v1/chat/completions استفاده کنید.
  • برای SDK مدل Anthropic یا قالب درخواست سازگار با آن از v1/messages استفاده کنید.
  • برای فیلدهای درخواست و ابزارهای اختصاصی Gemini از API بومی v1beta/ استفاده کنید.
  • تنها پس از تأیید پشتیبانی تمام پارامترها و ابزارهای موردنیاز گردش‌کار از v1/responses استفاده کنید.

نمونه سازگار با OpenAI ​

bash
curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gemini-3.7-flash",
    "messages": [{"role": "user", "content": "این معماری را بررسی کن و یک برنامه پیاده‌سازی مرحله‌ای برگردان."}]
  }'
python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.chat.completions.create(
    model="gemini-3.7-flash",
    messages=[
        {
            "role": "user",
            "content": "این معماری را بررسی کن و یک برنامه پیاده‌سازی مرحله‌ای برگردان.",
        }
    ],
)

print(response.choices[0].message.content)
javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.chat.completions.create({
  model: "gemini-3.7-flash",
  messages: [
    {
      role: "user",
      content: "این معماری را بررسی کن و یک برنامه پیاده‌سازی مرحله‌ای برگردان.",
    },
  ],
});

console.log(response.choices[0].message.content);

نمونه API بومی Gemini ​

bash
curl https://api.avalai.ir/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "یک عامل ابزارمحور و قابل اتکا برای triage رخدادها طراحی کن."}]
      }
    ]
  }'

راهنمای استفاده در production ​

  • کلیدهای API را روی سرور نگه دارید و از متغیرهای محیطی بارگذاری کنید.
  • پیش از انتقال ترافیک production، پرامپت‌ها، ابزارها و ورودی‌های چندوجهی واقعی را ارزیابی کنید.
  • برای خطاهای موقت retry همراه با backoff اضافه کنید و محدودیت‌های نرخ را در نظر بگیرید.
  • حتی هنگام استفاده از response schema، خروجی ساختاریافته را در کد برنامه اعتبارسنجی کنید.
  • بارهای کاری بلندمدت را بر اساس نرخ استاندارد Gemini 3.7 Flash پس از ۳۱ دسامبر ۲۰۲۶ پیش‌بینی کنید.

مستندات مرتبط ​