# شروع سریع

> نخستین درخواست به هدهد و سنجه با نمونه‌های curl، Python و Node.js

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

سه قدم تا نخستین پاسخ: کلید بسازید، در متغیر محیطی بگذارید، یک متن انگلیسی برای ترجمه بفرستید. بعد همان کلید را روی سنجه امتحان کنید.

## ۱. کلید API بسازید

در [کنسول دانا](https://console.dana.expert/keys) روی ساخت کلید بزنید و نامی بگذارید که بشناسیدش. کلید با `dn-live-` شروع می‌شود و **فقط همان یک بار** کامل نشان داده می‌شود، پس همان‌جا کپی کنید.

## ۲. کلید را در محیط بگذارید

```bash
export DANA_API_KEY="dn-live-..."
```

## ۳. یک متن ترجمه کنید

**curl:**

```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."}'
```

**Python:**

```python
import os

import requests

r = requests.post(
    "https://api.dana.expert/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['DANA_API_KEY']}"},
    json={"text": "The meeting moved to Tuesday."},
    timeout=60,
)
r.raise_for_status()
print(r.json()["text"])
```

**Node.js:**

```js
const r = await fetch("https://api.dana.expert/v1/translate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "The meeting moved to Tuesday." }),
});
console.log((await r.json()).text);
```

## پاسخ موفق

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

`model_version` نسخهٔ مترجمی است که جواب داده: هدهد v2.3. جزئیات لحن و فیلدها در [مترجم](https://dana.expert/docs/translate) است.

## بعد از ترجمه، سنجه را امتحان کنید

همان کلید روی `POST /v1/decide` هم کار می‌کند. یک متن و یک پرسش بله یا خیر بفرستید:

```bash
curl https://api.dana.expert/v1/decide \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "سه روز است سفارشم را پرداخت کرده‌ام ولی هنوز ارسال نشده.",
    "questions": {"complaint": {"type": "noul", "instructions": "آیا این پیام شکایت است؟"}}
  }'
```

جواب احتمال «بله» را می‌دهد، مثلا `"noul": 0.9521`، همراه `"model": "ghanari"` و `"model_version": "ghanari-ir-v0.1"`. سه نوع پرسش و مدل کبوتر در [سنجه](https://dana.expert/docs/decide) آمده است.

## اگر جواب نگرفتید

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

فهرست کامل کدها و راه‌حل هرکدام در [خطاها](https://dana.expert/docs/errors) آمده است. هدر درست `Authorization: Bearer <key>` است؛ کلید بدون `Bearer` همان `401` را می‌دهد.

## گفت‌وگو با هما

همان کلید روی هما هم کار می‌کند: `"model": "homa"` را به `POST /v1/chat/completions` یا `POST /v1/messages` بفرستید. نمونه و محدودیت‌ها در [هما](https://dana.expert/docs/homa) آمده است.

## قدم بعدی

- [مترجم](https://dana.expert/docs/translate): لحن، فیلدهای پاسخ و هزینه
- [سنجه](https://dana.expert/docs/decide): سه نوع پرسش و دو مدل قناری و کبوتر
- [هما](https://dana.expert/docs/homa): گفت‌وگو به فارسی، پارامترها و محدودیت‌ها
- [حساب و کلید API](https://dana.expert/docs/authentication): حساب، کلید `live` و `test` و نگهداری امن آن‌ها
- [محدودیت‌ها](https://dana.expert/docs/rate-limits): سقف نرخ و مدیریت `429`