# هدهد، مترجم

> ترجمهٔ انگلیسی به فارسی با هدهد: درخواست، لحن، پاسخ و هزینه

URL: https://dana.expert/docs/translate

`POST /v1/translate` متن انگلیسی را با مترجم هدهد (نسخهٔ فعلی v2.3) به فارسی روان برمی‌گرداند. بلوک‌های کد اصلا به مدل داده نمی‌شوند و همان‌طور برمی‌گردند. مدل برای دست نزدن به کد اینلاین، عدد، لینک و اصطلاح فنی آموزش دیده و خروجی‌اش برای کد اینلاین بررسی می‌شود، ولی بی‌خطا نیست. بخشی که درست ترجمه نشود انگلیسی می‌ماند و `fallback` در پاسخ `true` می‌شود.

در آزمون خود مدل روی ۱۲۰ متن، ۱۶ متن دست‌کم یک خطا داشتند؛ حذف کد هم ثبت شده است. این سنجش با رفتار محافظتی API فرق دارد. خروجی نهایی را پیش از استفاده بررسی کنید.

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

## نمونه

```bash
curl https://api.dana.expert/v1/translate \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "The meeting moved to Tuesday.", "register": "auto"}'
```

پاسخ:

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

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

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

## لحن

- `formal`: رسمی، با «شما».
- `informal`: خودمانی، با «تو».
- `auto`: لحن را از خود متن تشخیص می‌دهد و اگر مطمئن نباشد رسمی می‌نویسد.

## پاسخ

| فیلد | توضیح |
|---|---|
| `text` | ترجمهٔ فارسی |
| `register` | لحنی که به کار رفت؛ با `auto` همان است که مترجم تشخیص داده |
| `model` | همیشه `dana-translator` |
| `model_version` | نسخهٔ مترجمی که جواب داده، الان `hodhod-v2.3` (هدهد v2.3) |
| `fallback` | `true` یعنی بخشی از متن ترجمه نشد و انگلیسی ماند |
| `usage` | توکن‌های ورودی و خروجی همین درخواست |

## هزینه و محدودیت

توکن‌های متن ورودی و ترجمه از اعتبار کم می‌شوند: هر یک میلیون توکن ورودی ۱۰٬۰۰۰ تومان و خروجی ۴۰٬۰۰۰ تومان ([قیمت و توکن](https://dana.expert/docs/pricing-and-tokens)). سقف درخواست همان سقف کلید است ([محدودیت‌ها](https://dana.expert/docs/rate-limits)). متن شما و ترجمه‌اش جایی ذخیره نمی‌شوند؛ فقط تعداد توکن‌ها ثبت می‌شود.

## خطاها

| کد | یعنی |
|---|---|
| `400` | `text` خالی، بیش از اندازه، یا `direction` و `register` نامعتبر |
| `401` | کلید نیست یا شناخته نشد |
| `429` | سقف درخواست یا اعتبار تمام شده |
| `503` | با `code` برابر `model_unavailable`: مترجم همین حالا در دسترس نیست؛ چند دقیقه بعد دوباره بفرستید. با `coming_soon`: سرویس موقتا خاموش است |

شرح کامل هر کد در [خطاها](https://dana.expert/docs/errors) است. فیلدها و نمونه‌ها به شکل قرارداد در [مرجع API](https://dana.expert/docs/api-reference/translate) هم آمده‌اند.