Chat Completions

POSThttps://api.dana.expert/v1/chat/completions

هدرها

Authorizationstringالزامی
کلید API از کنسول دانا: Authorization: Bearer dn-live-...
x-api-keystring
همان کلید، به‌جای هدر Authorization
Content-Typestringالزامی
مقدار: "application/json"

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

modelstringالزامی
شناسهٔ مدل: homa
messagesobject[]الزامی
تاریخچهٔ گفت‌وگو
فیلدهای هر عضو messages
- rolestringالزامی
  مقدارها: "system""user""assistant""tool"
- contentstring | object[]الزامی
  متن پیام یا فهرست بخش‌ها
max_tokensinteger
سقف توکن خروجی؛ پیش‌فرض و حداکثر ۴٬۰۹۶. عدد بزرگ‌تر به ۴٬۰۹۶ کم می‌شود
پیش‌فرض: 4096حداکثر ۴٬۰۹۶
temperaturenumber
۰ تا ۲
top_pnumber
streamboolean
true یعنی پاسخ استریم با SSE
پیش‌فرض: false
stopstring | string[]
toolsobject[]
ابزارها با ساختار OpenAI
tool_choiceany
انتخاب ابزار با ساختار OpenAI

پاسخ `200`

پاسخ هما، با ساختار OpenAI

idstring
objectstring
مقدار: "chat.completion"
createdinteger
modelstring
choicesobject[]
فیلدهای هر عضو choices
- indexinteger
- messageobject
  فیلدهای message
  - rolestringالزامی
    مقدارها: "system""user""assistant""tool"
  - contentstring | object[]الزامی
    متن پیام یا فهرست بخش‌ها
- finish_reasonstring
usageobject
فیلدهای usage
- prompt_tokensintegerالزامی
  توکن‌های ورودی
- completion_tokensintegerالزامی
  توکن‌های خروجی
- total_tokensintegerالزامی
  جمع دو عدد بالا

هدرهای پاسخ

x-dana-cold-startstring
1 وقتی هما پیش از این جواب در حافظه بارگذاری شد؛ چنین پاسخی چند ثانیه بیشتر طول کشیده است. در بقیهٔ پاسخ‌ها نمی‌آید.

خطاها

کد	یعنی
`400`	بدنهٔ درخواست درست نیست؛ پیام می‌گوید کدام فیلد
`401`	کلید نرسید یا شناخته نشد
`429`	سقف درخواست، ظرفیت یا اعتبار؛ `type` و `code` علت را می‌گویند
`503`	`model_unavailable`: هما همین حالا در دسترس نیست؛ چند دقیقه بعد دوباره بفرستید. `coming_soon`: شناسهٔ مدلی جز `homa` خواسته‌اید که هنوز باز نیست

همهٔ کدها، علت و راه‌حل هرکدام در خطاها آمده است.

نمونهٔ درخواست

curl -X POST 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
  }'

import os

import requests

r = requests.post(
    "https://api.dana.expert/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['DANA_API_KEY']}"},
    json={
        "model": "homa",
        "messages": [
            {
                "role": "user",
                "content": "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»",
            },
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
print(r.json())

const r = await fetch("https://api.dana.expert/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "homa",
    "messages": [
      {
        "role": "user",
        "content": "این جمله را رسمی‌تر بنویس: «فردا جلسه رو کنسل کن.»"
      }
    ],
    "max_tokens": 200
  }),
});
console.log(await r.json());

نمونهٔ پاسخ 200

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

نمونهٔ خطا 401

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

Chat Completions

هدرها

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

پاسخ 200

هدرهای پاسخ

خطاها

پاسخ `200`