گفتگو با مدل‌های زبانی (Chat Completions)

با همان مدل‌های مغز بنانا گفتگو کنید. فرمت درخواست و پاسخ با OpenAI Chat Completions سازگار است؛ پاسخ همان لحظه برمی‌گردد (task و polling ندارد). هزینه بر اساس توکن مصرفی است (نرخ جدا برای ورودی، ورودی کش‌شده و خروجی به ازای هر ۱ میلیون توکن) و در لحظه پاسخ کسر می‌شود؛ اگر مدل پاسخی ندهد اعتبار برمی‌گردد.

مدل‌ها

در فیلد model هم شناسه کامل (مثل gpt-6-astra) و هم نام کوتاه (مثل astra) پذیرفته می‌شود. اگر model نفرستید gpt-6-luna استفاده می‌شود.

درخواست

• model (optional, string): شناسه مدل یا نام کوتاه آن. پیش‌فرض: gpt-6-luna.
  • examples: gpt-6-astra, astra, claude-haiku-5-5, haiku, claude-opus-5-5, claude-sonnet-5-5, grok-4.7
• messages (required, object[]): آرایه‌ای از {role, content}. role یکی از system | user | assistant (developer هم به system نگاشت می‌شود). content یا رشته است یا آرایه‌ای از بخش‌های {type:"text", text} و {type:"image_url", image_url:{url}}. حداکثر ۱۰۰ پیام، هر پیام ۳۲٬۰۰۰ کاراکتر، مجموع ۲۰۰٬۰۰۰ کاراکتر، تا ۴ عکس در هر پیام کاربر.
• stream (optional, boolean): true → پاسخ SSE با chunkهای chat.completion.chunk و در انتها data: [DONE]. پیش‌فرض false.
• temperature (optional, number): بین ۰ و ۲. اختیاری.
• top_p (optional, number): بین ۰ و ۱. اختیاری.
• max_tokens (optional, integer): سقف توکن خروجی (۱ تا ۳۲۷۶۸). اختیاری.

نمونه curl

curl -X POST "https://api.bananaai.ir/api/v1/chat/completions" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-astra","messages":[{"role":"system","content":"You are a concise assistant."},{"role":"user","content":"سه ایده برای کپشن اینستاگرام یک کافه بده."}]}'

نمونه JavaScript

const response = await fetch("https://api.bananaai.ir/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer ba_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise assistant."
    },
    {
      "role": "user",
      "content": "سه ایده برای کپشن اینستاگرام یک کافه بده."
    }
  ]
}),
});
const completion = await response.json();
console.log(completion.choices[0].message.content);

پاسخ

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1726000000,
  "model": "gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "۱) ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 42, "completion_tokens": 128, "total_tokens": 170 },
  "credits_charged": 5
}

• choices[0].message.content: متن پاسخ.
• credits_charged: اعتباری که برای این درخواست کسر شد (بر اساس توکن‌های واقعی مصرف‌شده).
• usage: اگر ارائه‌دهنده تعداد توکن را برگرداند؛ در محاسبه هزینه نقشی ندارد.

پاسخ تکه‌تکه (stream)

با "stream": true پاسخ text/event-stream است. هر خط data: یک JSON با object: "chat.completion.chunk" و choices[0].delta.content دارد. chunk آخر finish_reason و credits_charged را دارد و بعد از آن data: [DONE] می‌آید.

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","model":"gpt-6-astra","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","model":"gpt-6-astra","choices":[{"index":0,"delta":{"content":"۱) "},"finish_reason":null}]}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","model":"gpt-6-astra","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"credits_charged":5}

data: [DONE]

در حالت stream هدر Idempotency-Key نادیده گرفته می‌شود. اگر خطا بعد از شروع پاسخ رخ دهد، یک رویداد data: {"error": {...}} می‌آید.

ارسال عکس (vision)

در پیام‌های user می‌توانید به‌جای رشته، آرایه‌ای از بخش‌ها بفرستید. آدرس عکس باید عمومی (http/https) یا data URI باشد.

{
  "model": "claude-sonnet-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "این عکس چه چیزی را نشان می‌دهد؟" },
        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
      ]
    }
  ]
}

استفاده با SDK OpenAI

چون فرمت سازگار است، می‌توانید base_url کلاینت OpenAI را به https://api.bananaai.ir/api/v1 تغییر دهید و کلید بنانا را به‌عنوان api_key بدهید:

from openai import OpenAI

client = OpenAI(base_url="https://api.bananaai.ir/api/v1", api_key="ba_live_your_api_key")
completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "سلام!"}],
)
print(completion.choices[0].message.content)

خطاها

• 400 unsupported_model: شناسه مدل ناشناخته است (فهرست: GET /api/v1/models?type=chat).
• 400 invalid_request: بدنه نامعتبر یا مدل ورودی را رد کرد (مثلاً URL عکس غیرقابل دسترس).
• 403 insufficient_credits: اعتبار کافی نیست.
• 500 generation_failed: ارائه‌دهنده پاسخ نداد؛ اعتباری کسر نشده.