---
title: Chat Completions
description: "رابط سازگار با OpenAI دانا: پارامترها، streaming، هدرها و ساختار پاسخ"
---

`POST /v1/chat/completions` رابط اصلی سازگار با OpenAI است. اگر کدی دارید که با openai SDK کار می‌کند، فقط `base_url` و کلید را عوض کنید.

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

## نمونه کامل

**curl:**

```bash
curl https://api.dana.expert/v1/chat/completions \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dana-1",
    "messages": [
      {"role": "system", "content": "دستیار فارسی‌زبان هستید."},
      {"role": "user", "content": "پایتخت ایران کجاست؟"}
    ]
  }'
```

**Python (openai SDK):**

```python
import os

from openai import OpenAI

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

response = client.chat.completions.create(
    model="dana-1",
    messages=[
        {"role": "system", "content": "دستیار فارسی‌زبان هستید."},
        {"role": "user", "content": "پایتخت ایران کجاست؟"},
    ],
)
print(response.choices[0].message.content)
```

**Node.js (openai SDK):**

```js
import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "dana-1",
  messages: [
    { role: "system", content: "دستیار فارسی‌زبان هستید." },
    { role: "user", content: "پایتخت ایران کجاست؟" },
  ],
});
console.log(response.choices[0].message.content);
```

## پارامترها

فقط دو پارامتر اجباری است:

| پارامتر | نوع | توضیح |
|---|---|---|
| `model` | string | شناسه مدل، مثل `dana-1` یا `dana-1-fast` |
| `messages` | array | آرایه پیام‌های مکالمه |

بقیه اختیاری‌اند:

| پارامتر | نوع | توضیح |
|---|---|---|
| `stream` | boolean | پاسخ به شکل SSE؛ پیش‌فرض `false` |
| `max_tokens` | integer | سقف توکن خروجی |
| `max_completion_tokens` | integer | نام تازه‌تر همان `max_tokens` |
| `temperature` | number | تنوع خروجی، از ۰ تا ۲ |
| `top_p` | number | nucleus sampling |
| `n` | integer | تعداد پاسخ‌های موازی |
| `stop` | string یا array | توالی‌های توقف |
| `seed` | integer | برای خروجی تکرارپذیرتر |
| `response_format` | object | مثلا حالت JSON |
| `tools` | array | تعریف ابزارها برای tool calling |
| `tool_choice` | string یا object | انتخاب اجباری یا خودکار ابزار |
| `parallel_tool_calls` | boolean | اجازه فراخوانی هم‌زمان چند ابزار |
| `frequency_penalty` | number | کم کردن تکرار واژه |
| `presence_penalty` | number | تشویق به موضوع تازه |
| `logprobs` | boolean | برگرداندن احتمال توکن‌ها |
| `top_logprobs` | integer | چند گزینه برتر در `logprobs` |
| `logit_bias` | object | دست بردن در شانس توکن‌های مشخص |
| `user` | string | شناسه کاربر نهایی برای پیگیری |

پارامتری که در این فهرست نیست هم دور ریخته نمی‌شود؛ دانا آن را دست‌نخورده به موتور مدل می‌فرستد. سقف `max_tokens` هم یک حد بالای سمت سرور دارد و مقدار بزرگ‌تر تا همان حد کوتاه می‌شود.

### ساختار پیام

```json
{"role": "system", "content": "متن پیام"}
```

مقدار `role` یکی از `system` و `user` و `assistant` است.

## هدرهای اختصاصی دانا

| هدر | مقدار | کار |
|---|---|---|
| `X-Dana-Harness` | `none` یا `base` یا `agent` | پروفایل بهبود فارسی؛ پیش‌فرض `base` |
| `X-Dana-Effort` | `low` تا `max` | میزان تلاش مدل و سقف پیش‌فرض خروجی |

مقدار نامعتبر روی هرکدام، `400` می‌گیرد.

## Streaming

با `"stream": true` پاسخ به شکل رویدادهای SSE می‌آید:

```bash
curl https://api.dana.expert/v1/chat/completions \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"dana-1","stream":true,"messages":[{"role":"user","content":"یک داستان کوتاه بگو"}]}'
```

هر رویداد یک خط `data:` است و جریان با `[DONE]` تمام می‌شود:

```
data: {"id":"chatcmpl-xyz","object":"chat.completion.chunk","choices":[{"delta":{"content":"یک"},"index":0}]}

data: [DONE]
```

آمار مصرف در رویداد پایانی جریان می‌آید، نه در تک‌تک تکه‌ها.

## ساختار پاسخ

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "dana-1",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "تهران پایتخت ایران است."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 10,
    "total_tokens": 32
  }
}
```

مقدار `finish_reason` می‌گوید چرا تولید ایستاد. `stop` یعنی پاسخ کامل شد و `length` یعنی به سقف `max_tokens` خورده است. اگر پاسخ‌ها نصفه می‌مانند، سراغ همین فیلد بروید.

## صفحه‌های مرتبط

- [شروع سریع](/docs/quickstart) - نخستین درخواست موفق
- [Messages](/docs/messages) - همین کار با رابط Anthropic
- [خطاها](/docs/errors) - هر کد خطا و راه‌حلش
- [قیمت و توکن](/docs/pricing-and-tokens) - معنی `usage`