# Chat Completions

> رابط سازگار با OpenAI برای گفت‌وگو با هما (`"model": "homa"`). خروجی هر پاسخ تا ۴٬۰۹۶ توکن است و ورودی و خروجی روی هم تا ۸٬۱۹۲ توکن.

URL: https://dana.expert/docs/api-reference/chat-completions

`POST https://api.dana.expert/v1/chat/completions`

## هدرها

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `Authorization` | string | بله | کلید API از کنسول دانا: `Authorization: Bearer dn-live-...` |
| `x-api-key` | string | نه | همان کلید، به‌جای هدر `Authorization` |
| `Content-Type` | string | بله | مقدار: `"application/json"` |

## بدنهٔ درخواست

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `model` | string | بله | شناسهٔ مدل: `homa` |
| `messages` | object[] | بله | تاریخچهٔ گفت‌وگو |
| `max_tokens` | integer | نه | سقف توکن خروجی؛ پیش‌فرض و حداکثر ۴٬۰۹۶. عدد بزرگ‌تر به ۴٬۰۹۶ کم می‌شود؛ پیش‌فرض: `4096`؛ حداکثر ۴٬۰۹۶ |
| `temperature` | number | نه | ۰ تا ۲ |
| `top_p` | number | نه |  |
| `stream` | boolean | نه | `true` یعنی پاسخ استریم با SSE؛ پیش‌فرض: `false` |
| `stop` | string \| string[] | نه |  |
| `tools` | object[] | نه | ابزارها با ساختار OpenAI |
| `tool_choice` | any | نه | انتخاب ابزار با ساختار OpenAI |

**فیلدهای هر عضو messages:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `role` | string | بله | مقدار: `"system"`، `"user"`، `"assistant"`، `"tool"` |
| `content` | string \| object[] | بله | متن پیام یا فهرست بخش‌ها |

نمونه:

```json
{
  "model": "homa",
  "messages": [
    {
      "role": "user",
      "content": "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»"
    }
  ],
  "max_tokens": 200
}
```

## پاسخ `200`

پاسخ هما، با ساختار OpenAI

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `id` | string | نه |  |
| `object` | string | نه | مقدار: `"chat.completion"` |
| `created` | integer | نه |  |
| `model` | string | نه |  |
| `choices` | object[] | نه |  |
| `usage` | object | نه |  |

**فیلدهای هر عضو choices:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `index` | integer | نه |  |
| `message` | object | نه |  |
| `finish_reason` | string | نه |  |

**فیلدهای message:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `role` | string | بله | مقدار: `"system"`، `"user"`، `"assistant"`، `"tool"` |
| `content` | string \| object[] | بله | متن پیام یا فهرست بخش‌ها |

**فیلدهای usage:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `prompt_tokens` | integer | بله | توکن‌های ورودی |
| `completion_tokens` | integer | بله | توکن‌های خروجی |
| `total_tokens` | integer | بله | جمع دو عدد بالا |

### هدرهای پاسخ

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `x-dana-cold-start` | string | نه | `1` وقتی هما پیش از این جواب در حافظه بارگذاری شد؛ چنین پاسخی چند ثانیه بیشتر طول کشیده است. در بقیهٔ پاسخ‌ها نمی‌آید. |

نمونه:

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1793418932,
  "model": "homa",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "جلسهٔ فردا لغو شود."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 11,
    "total_tokens": 43
  }
}
```

## خطاها

| کد | یعنی |
|---|---|
| `400` | بدنهٔ درخواست درست نیست؛ پیام می‌گوید کدام فیلد |
| `401` | کلید نرسید یا شناخته نشد |
| `429` | سقف درخواست، ظرفیت یا اعتبار؛ `type` و `code` علت را می‌گویند |
| `503` | `model_unavailable`: هما همین حالا در دسترس نیست؛ چند دقیقه بعد دوباره بفرستید. `coming_soon`: شناسهٔ مدلی جز `homa` خواسته‌اید که هنوز باز نیست |

فرمت خطا:

```json
{
  "error": {
    "message": "Request body must include 'text' as a string.",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
```