Chat Completions
POST /v1/chat/completions
مستندات
معرفی
شما پیامها را میفرستید و مدل، پیام بعدی را مینویسد. همین. پرسش و پاسخ، خلاصهسازی، ترجمه، تولید کد و دستهبندی متن، همه با همین یک درخواست انجام میشوند.
قالب درخواست و پاسخ عیناً همان چیزی است که OpenAI دارد، بنابراین هر SDK یا ابزاری که با OpenAI کار میکند با تغییر آدرس پایه اینجا هم کار میکند.
curl https://api-ai.hibanacloud.ir/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5-nano", "messages": [{"role": "user", "content": "سلام! یک لطیفه کوتاه بگو."}], "max_completion_tokens": 2000, "reasoning_effort": "low" }'فقط model و messages الزامیاند؛ بقیهٔ پارامترها اختیاریاند و در جدول پارامترها آمدهاند.
درخواست و پاسخ
POST https://api-ai.hibanacloud.ir/v1/chat/completions Headers: Content-Type: application/json Authorization: Bearer YOUR_API_TOKEN Body (JSON):{ "model": "gpt-5-nano", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "سلام! یک لطیفه کوتاه بگو." } ], "max_tokens": 4096}ساختار messages
هر عضو آرایهٔ messages یک شیء با دو کلید است: role و content. سه نقش وجود دارد:
| role | یعنی چه |
|---|---|
| system | دستور کلی به مدل: لحن، زبان، محدودیتها. معمولاً اولین پیام آرایه. |
| user | حرف کاربر. هر درخواست دستکم یکی از اینها لازم دارد. |
| assistant | پاسخ خودِ مدل. برای ادامهٔ گفتوگو، پاسخ قبلی را با همین نقش به آرایه برگردانید. |
API حافظه ندارد. برای ادامهٔ یک گفتوگو، کل تاریخچه را در هر درخواست دوباره بفرستید، پیامهای قبلی کاربر و پاسخهای قبلی مدل:
{ "model": "gpt-5-nano", "messages": [ { "role": "system", "content": "پاسخها را کوتاه و به فارسی بده." }, { "role": "user", "content": "پایتخت ژاپن کجاست؟" }, { "role": "assistant", "content": "توکیو." }, { "role": "user", "content": "جمعیتش چقدر است؟" } ]}هرچه تاریخچه بلندتر شود، prompt_tokens و در نتیجه هزینهٔ هر درخواست بیشتر میشود. نحوهٔ محاسبه در قیمتگذاری و صورتحساب است.
برای فرستادن تصویر همراه پیام، content بهجای یک رشته یک آرایه میشود، در ورودی تصویر توضیح داده شده است.
پارامترهای درخواست
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | کد نام مدل (مثال: gpt-5-nano, claude-sonnet-4-5) |
| messages | array | بله | آرایه پیامها با role و content |
| max_tokens | integer | خیر | حداکثر توکن برای تولید |
| temperature | float | خیر | دمای نمونهبرداری (۰ تا ۲) |
| top_p | float | خیر | پارامتر نمونهبرداری nucleus (۰ تا ۱) |
| stream | boolean | خیر | فعالسازی پاسخ جریانی (SSE) |
| stop | array | خیر | دنبالههای توقف |
| frequency_penalty | float | خیر | جریمه تکرار (-۲ تا ۲) |
| presence_penalty | float | خیر | جریمه حضور (-۲ تا ۲) |
| tools | array | خیر | تعریف ابزار برای function calling |
فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| id | string | شناسه یکتای درخواست |
| object | string | نوع شیء (chat.completion) |
| created | integer | زمان ایجاد (Unix timestamp) |
| model | string | کد مدل استفاده شده |
| choices | array | آرایه پاسخها |
| usage | object | شامل: prompt_tokens, completion_tokens, total_tokens, cost_rial |
متنی که معمولاً دنبالش هستید در choices[0].message.content است. مقدار finish_reason برابر "stop" یعنی مدل خودش به پایان رسیده است.
خطاها
فهرست خطاهای متداول، فرمت پاسخ خطا و نمونههای کامل در صفحهٔ مدیریت خطاها آمده است.
کوتاه: 401 کلید، 402 موجودی، 429 سقف نرخ، 400 بدنهٔ درخواست. اگر نشانهٔ مشکل را دارید ولی کد خطا را نه، از حل مشکلات شروع کنید.