پرش به محتوای اصلی

اولین درخواست

اولین درخواست

این صفحه دقیقاً یک کار می‌کند: شما را از «کلید دارم» به «پاسخ گرفته‌ام» می‌رساند. پیش از این صفحه باید یک API key داشته باشید؛ اگر ندارید از احراز هویت و امنیت کلید شروع کنید.

آماده‌سازی

سه مقدار را کنار هم بگذارید:

مقداراز کجا
DOTHOOSH_API_KEYکنسول، هنگام ساخت key (فقط یک بار نمایش داده می‌شود)
YOUR_MODELپاسخ GET /v1/models
آدرس پایهhttps://gateway.dothoosh.com/v1
bash
export DOTHOOSH_API_KEY="dh_live_…"
curl "https://gateway.dothoosh.com/v1/models" \
  -H "Authorization: Bearer $DOTHOOSH_API_KEY"

پاسخ یک فهرست است؛ یکی از idها را بردارید. فهرست برای هر key جداگانه ساخته می‌شود:

json
{
  "object": "list",
  "catalog_version": "…",
  "data": [
    {
      "id": "…",
      "object": "model",
      "created": 1774000000,
      "owned_by": "dothoosh",
      "status": "active",
      "capabilities": ["text", "streaming"],
      "protocols": [{ "protocol": "openai-chat-completions" }]
    }
  ]
}

بقیهٔ فیلدهای این پاسخ (از جمله policy و context_window) در صفحهٔ مدل‌ها توضیح داده شده‌اند.

درخواست chat completions

curl "https://gateway.dothoosh.com/v1/chat/completions" \
  -H "Authorization: Bearer $DOTHOOSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      { "role": "system", "content": "پاسخ کوتاه بده." },
      { "role": "user", "content": "تهران کجاست؟" }
    ]
  }'

model و messages تنها فیلدهای الزامی هستند. بقیهٔ فیلدها اختیاری‌اند و فقط اگر قابلیت‌شان برای همان مدل تأیید شده باشد پذیرفته می‌شوند؛ فیلد ناشناخته یا تأییدنشده با unsupported_parameter رد می‌شود. برای نمونه، سقف توکن خروجی را با max_completion_tokens بدهید (نه با max_tokens).

پاسخ موفق

json
{
  "id": "chatcmpl_…",
  "object": "chat.completion",
  "created": 1774000000,
  "model": "YOUR_MODEL",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 118,
    "total_tokens": 160
  }
}

usage همان چیزی است که برای تسویه اندازه‌گیری می‌شود. سرآیند X-Request-Id پاسخ را نگه دارید؛ در پیگیری هر مشکل به آن نیاز دارید.

اگر پاسخ نگرفتید

چه می‌بینیدیعنیکار بعدی
401 api_key_malformedسرآیند اشتباه، هر دو سرآیند با هم، یا مقدار کلید بی‌شکلفقط Authorization: Bearer <key> بفرستید و x-api-key را بردارید
401 api_key_invalidکلید ناشناخته استکلید را از کنسول دوباره کپی کنید؛ اگر لو رفته، لغو و کلید تازه بسازید
402 insufficient_available_balanceموجودی قابل‌استفادهٔ کیف پول کافی نیستکیف پول را شارژ کنید؛ این درخواست هیچ هزینه‌ای نداشته است
404 model_not_foundاین key به این مدل دسترسی ندارد یا مدل وجود نداردGET /v1/models را با همین key صدا بزنید
429 api_key_rpm_exceededسقف درخواست در دقیقهبه‌اندازهٔ Retry-After صبر کنید (محدودیت‌ها)
400 unsupported_parameterفیلدی فرستادید که این مسیر تأییدش نکردهفیلد را بردارید یا مقدار مجاز را از مرجع API بگیرید

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

مطالب مرتبط

گام بعدی