مستندات APIمسیرهاChat Completions

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

با GPT 6 Astra، Claude Haiku 5.5، Claude Opus 5، Grok 4.6، Gemini 3.5 Flash-Lite و بقیهٔ مدل‌ها گفتگو کنید. فرمت درخواست و پاسخ با OpenAI Chat Completions سازگار است و پاسخ همان لحظه برمی‌گردد.

نسخهٔ API: v1

مسیر درخواست

POSThttps://bananaai.ir/api/v1/chat/completions

یک پاسخ متنی از مدل زبانی انتخابی برمی‌گرداند. برخلاف مسیرهای عکس و ویدیو، این مسیر همگام است: پاسخ در همان درخواست می‌آید و تسکی برای پیگیری ساخته نمی‌شود. فرمت بدنه و پاسخ با OpenAI Chat Completions سازگار است، پس کلاینت‌های موجود با تغییر base_url کار می‌کنند.

هزینه

هر درخواست، مستقل از طول پیام‌ها و پاسخ، نرخ ثابت مدل را کسر می‌کند (۱ تا ۵ اعتبار). استثنا Gemini 3.5 Flash-Lite است که بر اساس توکن مصرفی حساب می‌شود: پیام‌های معمولی ۱ اعتبار، ولی پیام‌های طولانی، عکس‌های زیاد یا پاسخ‌های بلند بیشتر هزینه دارند (مقدار دقیق در credits_charged پاسخ). اگر مدل پاسخی تولید نکند، اعتبار برمی‌گردد. جزئیات در اعتبار و هزینه.

مدل‌ها

همان مدل‌های مغز بنانا در API هم در دسترس‌اند. در فیلد model شناسهٔ کامل یا نام کوتاه را بفرستید؛ اگر چیزی نفرستید، gpt-5.6-luna استفاده می‌شود.

مدل	نام کوتاه	اعتبار / درخواست	توضیح
gpt-5.6-lunaGPT 5.6 Luna	luna, gpt-5-6-luna	1	سریع و روان؛ ارزان‌ترین گزینه برای چت و خلاصه‌سازی.
gpt-5.6-terraGPT 5.6 Terra	terra, gpt-5-6-terra	2	متعادل و همه‌کاره برای تولید متن و پاسخ‌های روزمره.
gpt-5.6-solGPT 5.6 Sol	sol, gpt-5-6-sol	2	استدلال قوی‌تر برای تحلیل و کارهای چندمرحله‌ای.
gpt-6-astraGPT 6 Astra	astra, gpt-6, gpt6-astra	5	قوی‌ترین استدلال؛ مناسب مسائل پیچیده و متن‌های طولانی.
claude-haiku-5-5Claude Haiku 5.5	haiku, haiku-5.5, haiku-5-5, claude-haiku, claude-haiku-5.5	1	سریع و اقتصادی؛ ارزان‌ترین Claude برای چت، ترجمه و خلاصه‌سازی.
claude-sonnet-5Claude Sonnet 5	sonnet, sonnet-5, claude-sonnet	2	دقیق و متعادل با درک خوب از فارسی و کد.
claude-opus-5Claude Opus 5	opus, opus-5, claude-opus	4	عمیق و دقیق برای نوشتار حرفه‌ای و تحلیل سنگین.
grok-4.6Grok 4.6	grok, grok-4-6	2	سریع و صریح با دانش به‌روز.
gemini-3.5-flash-liteGemini 3.5 Flash-Lite	gemini, flash-lite, gemini-flash-lite, gemini-3-5-flash-lite	1	سریع و ارزان با پنجرهٔ زمینهٔ بزرگ؛ مناسب ترجمه، خلاصه‌سازی، دسته‌بندی و پردازش حجیم متن.

پارامترهای درخواست

بدنهٔ درخواست باید JSON باشد (Content-Type: application/json).

messagesobject[]الزامی: تاریخچهٔ گفتگو، از قدیمی‌ترین به جدیدترین. هر آیتم { role, content } است؛ role یکی از system، user یا assistant (developer به system نگاشت می‌شود). content یا رشته است یا آرایه‌ای از بخش‌های متنی و عکس (بخش ارسال عکس). حداکثر ۱۰۰ پیام، هر پیام ۳۲٬۰۰۰ کاراکتر و مجموعاً ۲۰۰٬۰۰۰ کاراکتر؛ دست‌کم یک پیام user لازم است.
modelstringاختیاری: شناسهٔ مدل یا نام کوتاه آن از جدول بالا. فهرست کامل با GET /api/v1/models?type=chat.; پیش‌فرض:gpt-5.6-lunaمثال:gpt-6-astraastraclaude-haiku-5-5haikuclaude-opus-5grok-4.6
streambooleanاختیاری: اگر true باشد، پاسخ به‌صورت Server-Sent Events و تکه‌تکه برمی‌گردد (بخش پاسخ تکه‌تکه).; پیش‌فرض:false
temperaturenumberاختیاری: میزان تنوع پاسخ، بین ۰ و ۲. مقدار کمتر پاسخ قطعی‌تر می‌دهد. اگر نفرستید، پیش‌فرض مدل اعمال می‌شود.; مثال:0.20.71
top_pnumberاختیاری: نمونه‌گیری هسته‌ای، بین ۰ و ۱. معمولاً یا این یا temperature را تنظیم کنید.
max_tokensintegerاختیاری: سقف توکن خروجی (۱ تا ۳۲٬۷۶۸). در هزینه تأثیری ندارد؛ فقط طول پاسخ را محدود می‌کند.; مثال:5122048

نمونه درخواست

bash

curl -X POST "https://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": "سه ایده برای کپشن اینستاگرام یک کافه بده."
    }
  ]
}'

پاسخ

پاسخ 200 شامل متن نهایی مدل است. فیلد credits_charged اعتباری را نشان می‌دهد که برای این درخواست کسر شد.

JSON

1{
2  "id": "chatcmpl_abc123",
3  "object": "chat.completion",
4  "created": 1726000000,
5  "model": "gpt-6-astra",
6  "choices": [
7    {
8      "index": 0,
9      "message": { "role": "assistant", "content": "۱) قهوهٔ صبح، شروع دوباره…" },
10      "finish_reason": "stop"
11    }
12  ],
13  "usage": { "prompt_tokens": 42, "completion_tokens": 128, "total_tokens": 170 },
14  "credits_charged": 5
15}

choices[0].message.contentstring: متن پاسخ مدل.
choices[0].finish_reasonstring: دلیل پایان پاسخ؛ معمولاً stop. اگر به max_tokens برخورد کند length است.
usageobject: تعداد توکن ورودی/خروجی اگر ارائه‌دهنده برگرداند. صرفاً اطلاعاتی است و در هزینه نقشی ندارد.
credits_chargedinteger: اعتبار کسرشده برای این درخواست (نرخ ثابت مدل).

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

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

text

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

data: {"id":"chatcmpl_x","object":"chat.completion.chunk","model":"gpt-6-astra","choices":[{"index":0,"delta":{"content":"باران "},"finish_reason":null}]}

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

data: [DONE]

JavaScript

const response = await fetch("https://bananaai.ir/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer ba_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "astra",
    stream: true,
    messages: [{ role: "user", content: "یک شعر کوتاه دربارهٔ باران بگو." }],
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const events = buffer.split("\n\n");
  buffer = events.pop() ?? "";
  for (const event of events) {
    const data = event.replace(/^data: /, "").trim();
    if (!data || data === "[DONE]") continue;
    const chunk = JSON.parse(data);
    process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
  }
}

هشدار

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

ارسال عکس

همهٔ مدل‌ها ورودی تصویری می‌پذیرند. در پیام‌های user به‌جای رشته، آرایه‌ای از بخش‌ها بفرستید؛ نشانی عکس باید عمومی (http/https) یا data: URI باشد و در هر پیام حداکثر ۴ عکس مجاز است.

JSON

1{
2  "model": "claude-sonnet-5",
3  "messages": [
4    {
5      "role": "user",
6      "content": [
7        { "type": "text", "text": "این عکس چه چیزی را نشان می‌دهد؟" },
8        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
9      ]
10    }
11  ]
12}

استفاده با SDK OpenAI

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

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://bananaai.ir/api/v1",
    api_key="ba_live_your_api_key",
)

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "سه ایده برای کپشن اینستاگرام یک کافه بده."},
    ],
)
print(completion.choices[0].message.content)

نکته

فقط chat/completions و models با SDK OpenAI سازگارند؛ برای عکس و ویدیو از مسیرهای اختصاصی بنانا استفاده کنید. خطاها با همان ساختار خطاها و پیام‌ها برمی‌گردند (unsupported_model برای شناسهٔ ناشناخته، insufficient_credits برای کمبود اعتبار).