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

> گفت‌وگوی فارسی با هما: کاربرد، نمونه، پارامترهای مهم و محدودیت‌ها

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

هما مدل گفت‌وگوی فارسی دانا است: مدلی کوچک، با حدود ۲ میلیارد پارامتر، که برای گفت‌وگو به فارسی ساخته شده است. برای کارهای کوتاه و روزمره مناسب است، مثل بازنویسی رسمی یا خودمانی یک متن، خلاصهٔ کوتاه، پیش‌نویس پیام و جواب به پرسش‌های ساده.

مدل کوچکی است و ممکن است با اطمینان جواب نادرست بدهد. برای دانستنی‌هایی که باید درست باشند، محاسبهٔ دقیق، کد و استدلال طولانی به آن تکیه نکنید و خروجی را پیش از استفاده بررسی کنید.

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

هر دو مسیر با `"model": "homa"` به هما می‌رسند. اولی سازگار با OpenAI است و دومی سازگار با Anthropic، و هر دو استریم دارند.

## نمونه

**curl:**

```bash
curl https://api.dana.expert/v1/chat/completions \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "homa",
    "messages": [{"role": "user", "content": "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»"}],
    "max_tokens": 200
  }'
```

**Python:**

```python
import os

from openai import OpenAI

client = OpenAI(base_url="https://api.dana.expert/v1", api_key=os.environ["DANA_API_KEY"])

r = client.chat.completions.create(
    model="homa",
    messages=[{"role": "user", "content": "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»"}],
    max_tokens=200,
)
print(r.choices[0].message.content)
```

**JavaScript:**

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.dana.expert/v1",
  apiKey: process.env.DANA_API_KEY,
});

const r = await client.chat.completions.create({
  model: "homa",
  messages: [{ role: "user", content: "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»" }],
  max_tokens: 200,
});
console.log(r.choices[0].message.content);
```

پاسخ، با فیلدهای اصلی:

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

با anthropic SDK هم همین کار را می‌کنید: `base_url` را `https://api.dana.expert` بگذارید، بدون `/v1`، و `model="homa"` بفرستید. جزئیات دو رابط در [Chat Completions](https://dana.expert/docs/chat-completions) و [Messages](https://dana.expert/docs/messages) است.

## پارامترهای مهم

| پارامتر | توضیح |
|---|---|
| `model` | `homa` |
| `messages` | پیام‌های گفت‌وگو، به ترتیب؛ پیام `system` هم پذیرفته می‌شود |
| `max_tokens` | سقف توکن خروجی؛ پیش‌فرض و حداکثر ۴٬۰۹۶. عدد بزرگ‌تر به ۴٬۰۹۶ کم می‌شود |
| `temperature` و `top_p` | تنوع خروجی |
| `stream` | `true` یعنی پاسخ استریم با SSE |
| `stop` | توالی‌هایی که تولید را متوقف می‌کنند |

اعتبار به اندازهٔ ورودی به‌علاوهٔ `max_tokens` رزرو می‌شود و بعد از پاسخ، باقی‌اش برمی‌گردد. عددی بگذارید که واقعا لازم دارید ([قیمت و توکن](https://dana.expert/docs/pricing-and-tokens)).

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

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

## خطاها

| کد | یعنی |
|---|---|
| `400` | بدنهٔ درخواست درست نیست، مثلاً `messages` ندارد |
| `401` | کلید نیست یا شناخته نشد |
| `429` | سقف درخواست یا اعتبار تمام شده |
| `503` | با `code` برابر `model_unavailable`: هما همین حالا در دسترس نیست؛ چند دقیقه بعد دوباره بفرستید |

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