فراخوانی تابع، خروجی ساختاریافته و ورودی تصویر
دروازه بدنهٔ درخواست را ترجمه نمیکند: فیلدهای tools و tool_choice، response_format (از جمله json_schema) و بخشهای image_url همانطور که فرستادهای به سازندهٔ مدل میرسند و پاسخ او همانطور برمیگردد. پس هر مدلی که این قابلیتها را نزد سازندهٔ خودش دارد، اینجا هم دارد؛ اینکه یک مدل مشخص کدام را میپذیرد با سازندهٔ آن است. ابزارهای سمت سرور حساب جدایی دارند: فقط آنهایی مجازند که هزینهشان قابل اندازهگیری است.
آخرین بهروزرسانی:
فهرست مستندات
مسیرهای API
حساب، کلید و تیم
فراخوانی تابع و خروجی ساختاریافته · ۱
چه چیزی عبور میکند
| قابلیت | فیلدها | مسیر |
|---|---|---|
| فراخوانی تابع | tools (type: "function"), tool_choice, parallel_tool_calls | /v1/chat/completions, /v1/responses |
| خروجی ساختاریافته | response_format (json_object, json_schema) | /v1/chat/completions |
| ورودی تصویر | بخش image_url در content (نشانی یا data URL) | /v1/chat/completions |
| ورودی صدا | بخش input_audio در content | /v1/chat/completions |
| پارامترهای استدلال | reasoning_effort, reasoning | /v1/chat/completions, /v1/responses |
| ابزارهای Anthropic | tools, tool_choice, thinking, cache_control | /anthropic/v1/messages |
| ابزارهای Gemini | tools.functionDeclarations, generationConfig.responseSchema | /gemini/v1beta/models/{model}:generateContent |
- تنها تغییرهایی که دروازه در بدنه میدهد در این فهرست است. یکی از آنها به این صفحه مربوط است: برای مدلهای DeepSeek،
json_schemaبهjson_objectتبدیل میشود (طرحواره را در پرامپت هم بنویس). - اگر مدلی فیلدی را نپذیرد، خطای خود سازنده با همان وضعیت به تو میرسد و هزینهای ندارد.
- تصویر و فایل درون درخواست در حجم بدنه شمرده میشوند.
فراخوانی تابع و خروجی ساختاریافته · ۲
نمونه: فراخوانی تابع
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-mini",
"messages": [{"role": "user", "content": "هوای تهران چطور است؟"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}'پاسخ در choices[0].message.tool_calls نام تابع و آرگومانها را دارد. تابع را خودت اجرا کن و نتیجه را با پیامی به نقش tool و همان tool_call_id برگردان.
فراخوانی تابع و خروجی ساختاریافته · ۳
نمونه: خروجی ساختاریافته
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-mini",
"messages": [{"role": "user", "content": "نام و سال انتشار یک کتاب معروف را بده."}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "book",
"strict": true,
"schema": {
"type": "object",
"properties": {"title": {"type": "string"}, "year": {"type": "integer"}},
"required": ["title", "year"],
"additionalProperties": false
}
}
}
}'فراخوانی تابع و خروجی ساختاریافته · ۴
نمونه: ورودی تصویر
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.5-flash",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "در این تصویر چه میبینی؟"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
]
}]
}'تصویر را بهصورت data URL (base64) بفرست تا به در دسترس بودن یک نشانی از سمت سازنده وابسته نباشی. کل بدنهٔ درخواست تا ۲۵ مگابایت است.
فراخوانی تابع و خروجی ساختاریافته · ۵
ابزارهای سمت سرور
ابزار سمت سرور ابزاری است که خود سازنده اجرا میکند و جدا از توکنها هزینه دارد. فقط آنهایی مجازند که هزینهشان را میتوانیم دقیق حساب کنیم؛ بقیه پیش از فرستاده شدن رد میشوند و هزینهای ندارند.
| مسیر | مجاز | ردشده |
|---|---|---|
/v1/chat/completions | ابزارهای تابعی (function، custom)؛ فیلد web_search_options | هر نوع ابزار دیگر |
/v1/responses | ابزارهای تابعی و web_search | code_interpreter, file_search, image_generation, computer_use, mcp |
/anthropic/v1/messages | ابزارهای خودت، و web_search، web_fetch، bash، text_editor، computer و memory | code_execution |
/gemini/…:generateContent | functionDeclarations و grounding با Google Search | grounding با Google Maps |
- جستوجوی وب بهازای هر جستوجو و با نرخ جستوجوی همان مدل حساب میشود. پیش از تماس مبلغ چند جستوجو (تا ۳ در OpenAI و Anthropic) رزرو و پس از پاسخ به اندازهٔ جستوجوهای انجامشده کم میشود.
- مدلی که نرخ جستوجو ندارد با ابزار جستوجو خطای
400با کدsearch_not_pricedمیگیرد. - ابزار ردشده خطای
400با کدhosted_tool_unmeteredمیگیرد (در Gemini برای Google Maps خطای402با همین کد). - ابزارهای
bash،text_editor،computerوmemoryدر Anthropic را برنامهٔ خودت اجرا میکند؛ هزینهشان فقط توکن است.