# ترجمه

> متن انگلیسی را با هدهد به فارسی برمی‌گرداند. بلوک‌های کد دست نمی‌خورند. اگر بخشی درست ترجمه نشود، انگلیسی می‌ماند و `fallback` برابر `true` می‌شود.

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

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

## هدرها

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

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

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `text` | string | بله | متن انگلیسی؛ ۱ تا ۲۰٬۰۰۰ کاراکتر |
| `direction` | string | نه | جهت ترجمه؛ فعلا فقط `en-fa`؛ مقدار: `"en-fa"`؛ پیش‌فرض: `"en-fa"` |
| `register` | string | نه | لحن ترجمه: `formal` با «شما»، `informal` با «تو»، `auto` از روی خود متن؛ مقدار: `"auto"`، `"formal"`، `"informal"`؛ پیش‌فرض: `"auto"` |

نمونه:

```json
{
  "text": "The meeting moved to Tuesday.",
  "register": "auto"
}
```

## پاسخ `200`

ترجمهٔ فارسی

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `text` | string | بله | ترجمهٔ فارسی |
| `register` | string | بله | لحنی که به کار رفت؛ مقدار: `"auto"`، `"formal"`، `"informal"` |
| `model` | string | بله | همیشه `dana-translator`؛ مقدار: `"dana-translator"` |
| `model_version` | string | بله | نسخهٔ مترجمی که جواب داد، مثل `hodhod-v2.3` |
| `fallback` | boolean | بله | `true` یعنی بخشی از متن انگلیسی ماند |
| `usage` | object | بله | توکن‌های همین درخواست |

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

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

نمونه:

```json
{
  "text": "جلسه به روز سه‌شنبه موکول شد.",
  "register": "formal",
  "model": "dana-translator",
  "model_version": "hodhod-v2.3",
  "fallback": false,
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 22,
    "total_tokens": 28
  }
}
```

## خطاها

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

فرمت خطا:

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