# Messages

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

URL: https://dana.expert/docs/api-reference/messages

`POST https://api.dana.expert/v1/messages`

## هدرها

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

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

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `model` | string | بله | شناسهٔ مدل: `homa` |
| `max_tokens` | integer | بله | سقف توکن خروجی؛ پیش‌فرض و حداکثر ۴٬۰۹۶. عدد بزرگ‌تر به ۴٬۰۹۶ کم می‌شود؛ حداکثر ۴٬۰۹۶ |
| `messages` | object[] | بله |  |
| `system` | string \| object[] | نه | دستور سیستمی |
| `temperature` | number | نه | ۰ تا ۱ |
| `stream` | boolean | نه | پیش‌فرض: `false` |
| `stop_sequences` | string[] | نه |  |
| `tools` | object[] | نه | ابزارها با ساختار Anthropic |

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

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

نمونه:

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

## پاسخ `200`

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

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `id` | string | نه |  |
| `type` | string | نه | مقدار: `"message"` |
| `role` | string | نه | مقدار: `"assistant"` |
| `model` | string | نه |  |
| `content` | object[] | نه |  |
| `stop_reason` | string | نه |  |
| `usage` | object | نه |  |

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

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `input_tokens` | integer | نه |  |
| `output_tokens` | integer | نه |  |

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

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

نمونه:

```json
{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "model": "homa",
  "content": [
    {
      "type": "text",
      "text": "جلسهٔ فردا لغو شود."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 32,
    "output_tokens": 11
  }
}
```

## خطاها

| کد | یعنی |
|---|---|
| `400` | خطا با فرمت Anthropic؛ `type` و پیام، علت را می‌گویند |
| `401` | خطا با فرمت Anthropic؛ `type` و پیام، علت را می‌گویند |
| `429` | خطا با فرمت Anthropic؛ `type` و پیام، علت را می‌گویند |
| `503` | هما همین حالا در دسترس نیست؛ چند دقیقه بعد دوباره بفرستید |

فرمت خطا:

```json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}
```