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

`POST https://api.bananaai.ir/api/v1/chat/completions`


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

## مدل‌ها

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

> در فیلد `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

```bash
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

```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);
```

## پاسخ

```json
{
  "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]` می‌آید.

```text
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 باشد.

```json
{
  "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` بدهید:

```python
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`: ارائه‌دهنده پاسخ نداد؛ اعتباری کسر نشده.