راهنمای 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 |
| قرارداد زمینه Google | 1,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 اجرا نشده است. برای پاسخهای آموزشی متناظر و نمونههای نقاط پایانی سازگار، خبر انتشار را ببینید.
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/decisions | input | آرایه؛ شناسه هر پرسش در name؛ نوع دودویی predicate | آرایه پاسخ؛ usage.input_tokens / output_tokens |
System One /v1/systemone | state | نگاشت با کلید شناسه پرسش؛ نوع دودویی noul؛ criteria.true و false اختیاری | نگاشت پاسخ؛ usage.input_tokens / output_tokens |
Decisions بومی Google /v1beta/decisions | input | نگاشت با کلید شناسه پرسش؛ نوع دودویی 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
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": "این معماری را بررسی کن و یک برنامه پیادهسازی مرحلهای برگردان."}]
}'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)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
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 پس از ۳۱ دسامبر ۲۰۲۶ پیشبینی کنید.