مرجع API دیجی‌هوش

پیش‌نمایش: هنوز منتشر نشده است

این endpointها به‌صورت محلی پیاده‌سازی و با آزمون پذیرش تأیید شده‌اند، اما hostname تولیدی API هنوز اعلام نشده است. هر base URL و placeholder کلید را با مقدار محیط تأییدشده خود جایگزین کنید.

API عمومی نسخه ۱ دیجی‌هوش یک زیرمجموعه سخت‌گیرانه و نسخه‌بندی‌شده از Chat Completions را همراه کشف مدل و مصرف سازمان ارائه می‌کند:

POST /v1/chat/completions
GET  /v1/models
GET  /v1/usage

field ناشناخته یا پشتیبانی‌نشده با خطای پایدار رد می‌شود و هرگز بدون بررسی به ارائه‌دهنده مدل ارسال نمی‌شود.

احراز هویت و scopeها

کلید API سازمان دیجی‌هوش را در header استاندارد Bearer بفرستید:

Authorization: Bearer <YOUR_DIGIHOOSH_API_KEY>

Endpoint	scope لازم
POST /v1/chat/completions	chat:write
GET /v1/models	models:read
GET /v1/usage	usage:read

session cookie مرورگر این endpointها را احراز هویت نمی‌کند. Accept-Language: en یا Accept-Language: fa فقط متن خطا را انتخاب می‌کند؛ status code، کد خطا، شناسه‌ها و fieldهای ماشینی دیگر ثابت می‌مانند.

پیش از اجرای مثال‌ها placeholderها را یک‌بار تنظیم کنید:

export DIGIHOOSH_API_BASE_URL="http://localhost:8080"
export DIGIHOOSH_API_KEY="<YOUR_DIGIHOOSH_API_KEY>"

$env:DIGIHOOSH_API_BASE_URL = "http://localhost:8080"
$env:DIGIHOOSH_API_KEY = "<YOUR_DIGIHOOSH_API_KEY>"

POST /v1/chat/completions

یک اجرای stateless مدل ایجاد می‌کند و conversation داشبورد نمی‌سازد. fieldهای پذیرفته‌شده درخواست:

Field	قانون
model	شناسه مدل عمومی و الزامی؛ آن را از GET /v1/models بگیرید.
messages	پیام‌های متنی مرتب با roleهای system، user یا assistant.
stream	اختیاری؛ مقدار پیش‌فرض false است.
stream_options.include_usage	فقط هنگام stream: true مجاز است.
max_completion_tokens	عدد صحیح اختیاری از ۱ تا ۱۳۱۰۷۲.
temperature	عدد اختیاری از ۰ تا ۲.
reasoning_effort	مقدار اختیاری medium یا high.
n	اختیاری؛ فقط 1 پشتیبانی می‌شود.

tool، tool call، تصویر، صوت، metadata دلخواه، انتخاب provider، role برابر developer، مقدار n بزرگ‌تر از یک و field منسوخ max_tokens پشتیبانی نمی‌شوند.

درخواست غیرstreaming

payload تأییدشده زیر را با نام chat-request.json ذخیره کنید:

{
  "model": "gpt-5.6-luna",
  "messages": [
    {
      "role": "system",
      "content": "Answer concisely."
    },
    {
      "role": "user",
      "content": "What is two plus two?"
    }
  ],
  "stream": false,
  "max_completion_tokens": 64,
  "temperature": 0.2,
  "reasoning_effort": "high",
  "n": 1
}

با curl اجرا کنید:

curl --request POST "$DIGIHOOSH_API_BASE_URL/v1/chat/completions" --header "Authorization: Bearer $DIGIHOOSH_API_KEY" --header "Content-Type: application/json" --header "Accept-Language: fa" --data @chat-request.json

یا با PowerShell:

$headers = @{
    Authorization = "Bearer $env:DIGIHOOSH_API_KEY"
    "Accept-Language" = "fa"
}
Invoke-RestMethod -Method Post -Uri "$env:DIGIHOOSH_API_BASE_URL/v1/chat/completions" -Headers $headers -ContentType "application/json" -InFile "chat-request.json"

پاسخ موفق object: "chat.completion"، یک choice دستیار، مدل عمومی انتخاب‌شده و مصرف نهایی tokenهای prompt و completion دارد.

درخواست streaming

payload تأییدشده زیر را با نام chat-stream-request.json ذخیره کنید:

{
  "model": "gpt-5.6-luna",
  "messages": [
    {
      "role": "system",
      "content": "Answer concisely."
    },
    {
      "role": "user",
      "content": "What is two plus two?"
    }
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "max_completion_tokens": 64,
  "temperature": 0.2,
  "reasoning_effort": "high",
  "n": 1
}

curl --no-buffer --request POST "$DIGIHOOSH_API_BASE_URL/v1/chat/completions" --header "Authorization: Bearer $DIGIHOOSH_API_KEY" --header "Content-Type: application/json" --header "Accept: text/event-stream" --data @chat-stream-request.json

stream موفق از text/event-stream استفاده می‌کند. هر پیام به‌شکل data: <JSON> است. delta نخست role دستیار را اعلام می‌کند، deltaهای متن مرتب می‌مانند، دقیقاً یک choice دارای finish_reason غیرnull است و در صورت درخواست، یک chunk نهایی با choices خالی مصرف کامل را دارد. data: [DONE] همیشه آخرین داده است.

اگر درخواست پذیرفته‌شده در میانه stream شکست بخورد، envelope استاندارد خطا به‌عنوان یک data item و سپس [DONE] ارسال می‌شود. status HTTP پس از پذیرش تغییر نمی‌کند. لغو client به اجرا منتقل می‌شود و دیجی‌هوش stream ناقص را بدون اعلام retry نمی‌کند.

GET /v1/models

مدل‌های عمومی فعال دارای دقیقاً یک نرخ مؤثر مشتری را با ترتیب قطعی برمی‌گرداند. علاوه بر id،‏ object،‏ created و owned_by، هر مدل pricing.currency،‏ pricing.unit_tokens،‏ pricing.input_rate و pricing.output_rate دارد. نرخ‌ها مبلغ اعشاری دلار آمریکا به‌ازای واحد token اعلام‌شده‌اند؛ cached input جزو input و reasoning جزو output است و دوباره محاسبه نمی‌شود.

پاسخ هویت provider، تنظیم routing، هزینه provider،‏ markup،‏ discount یا margin را ندارد. نرخ‌های منتشرشده نرخ عملیاتی پیش از مالیات هستند، نه invoice یا مبلغ نهایی پرداخت. خرید اعتبار، پرداخت، مالیات و invoice در این preview در دسترس نیستند.

curl "$DIGIHOOSH_API_BASE_URL/v1/models" --header "Authorization: Bearer $DIGIHOOSH_API_KEY" --header "Accept-Language: fa"

GET /v1/usage

مصرف durable token سازمان احرازشده را برمی‌گرداند.

پارامتر query	قانون
from	instant الزامی RFC3339 و شامل‌شونده.
to	instant الزامی RFC3339، انحصاری و بعد از from.
model	فیلتر exact اختیاری مدل عمومی.
limit	مقدار اختیاری ۱ تا ۱۰۰؛ پیش‌فرض ۵۰.
cursor	cursor مات اختیاری صفحه پیشین.

بازه نمی‌تواند بیش از ۹۰ روز باشد. نتیجه با زمان ایجاد و شناسه درخواست از جدیدترین مرتب می‌شود. totals و by_model کل بازه فیلترشده را پوشش می‌دهند و data و next_cursor یک صفحه را توصیف می‌کنند. cursor به filterهای اولیه خود وابسته است.

curl "$DIGIHOOSH_API_BASE_URL/v1/usage?from=2099-08-01T00%3A00%3A00Z&to=2099-09-01T00%3A00%3A00Z&limit=50" --header "Authorization: Bearer $DIGIHOOSH_API_KEY" --header "Accept-Language: fa"

فقط شناسه درخواست، شناسه مدل عمومی، timestamp و تعداد token ثبت‌شده برمی‌گردد. prompt، response، داده provider، credential، قیمت، هزینه و داده conversation حذف می‌شوند.

شناسه درخواست و idempotency

هر پاسخ header برابر DigiHoosh-Request-Id دارد. می‌توانید این header را با مقدار منطبق بر req_[A-Za-z0-9_-]{8,120} روی درخواست chat بفرستید.

در یک سازمان، استفاده دوباره از شناسه همراه درخواست کامل‌شده یکسان، نمایش کامل‌شده را replay می‌کند. همان شناسه با payload متفاوت 409 idempotency_conflict می‌دهد و استفاده در زمان فعال‌بودن همان درخواست نیز به‌جای شروع اجرای دوم conflict می‌دهد. برای هر درخواست منطقی تازه، شناسه تازه بسازید.

محدودیت درخواست

پیش‌نمایش فعلی در هر دقیقه ثابت UTC برای هر سازمان ۶۰ درخواست جدید پذیرفته‌شده را می‌پذیرد. replay کامل‌شده idempotent سهمیه دیگری مصرف نمی‌کند. درخواست ردشده 429 rate_limit_exceeded با retryable: true و header برابر Retry-After از ۱ تا ۶۰ ثانیه دریافت می‌کند.

پیش از تلاش برای درخواست منطقی تازه به‌اندازه Retry-After صبر کنید. پس از دریافت هر event از SSE، retry خودکار نکنید.

وضعیت اعتبار و billing

درخواست Developer API اکنون برای reservation محافظه‌کارانه حداکثر مدل به اعتبار پیش‌پرداخت دلاری کافی نیاز دارد. هر credit برابر یک دلار آمریکا است. reservation فعال اعتبار در دسترس را کم می‌کند. درخواست completed با usage معتبر فقط یک بار debit دقیق قیمت مشتری را ثبت می‌کند و درخواست failed،‏ cancelled یا timeout مقدار مشتری را آزاد می‌کند. اگر شواهد نهایی نتواند درخواست را با اطمینان ببندد، reservation می‌تواند به‌جای حدس یا آزادشدن پنهان برای reconciliation نگه داشته شود. اعتبار ناکافی پیش از اجرای مدل با HTTP 402 و کد insufficient_credit رد می‌شود.

نرخ مؤثر هنگام پذیرش درخواست در snapshot کپی می‌شود. replay یکسان همان snapshot تاریخی را استفاده می‌کند و تغییر نرخ بعدی آن را دوباره قیمت‌گذاری نمی‌کند. مبلغ ورودی و خروجی جداگانه محاسبه، با روش midpoint-to-even تا ۱۲ رقم اعشار گرد و سپس جمع می‌شود. cached input جزو input و reasoning جزو output باقی می‌ماند؛ بنابراین هیچ‌کدام دوباره محاسبه نمی‌شود. گردکردن نمایشی نباید جای مقدار دقیق ذخیره‌شده را بگیرد.

سطح API key همچنان API موجودی، تراکنش، خرید، refund، پرداخت، مالیات، invoice یا دوره billing شمسی ندارد. نشست مرورگر احرازشده Owner یا Admin فقط می‌تواند خلاصه دقیق اعتبار API سازمان فعال خود را از GET /app/v1/billing/credit-summary و تاریخچه محدود اعتبار API را از GET /app/v1/billing/transactions بخواند؛ API key و Member به این routeها دسترسی ندارند. پیش‌نمایش منتشرنشده Developer Dashboard این readها را فقط به Owner یا Admin مجاز نشان می‌دهد؛ Chat اعتبار API را نمایش نمی‌دهد. تاریخچه تراکنش به‌طور پیش‌فرض ۲۵ و حداکثر ۱۰۰ ردیف را از جدیدترین به قدیمی‌ترین برمی‌گرداند و cursor مبهم آن به سازمان فعال وابسته است. این تاریخچه reservation در حال انتظار، debit نهایی، debit بازپرداخت‌شده، اعتبار تشویقی و reversal‏ append-only را با حفظ مقدار دقیق USD با ۱۲ رقم اعشار تفکیک می‌کند. reversal داخلی مصرف با یک رکورد append-only اعتبار را برمی‌گرداند؛ refund نقدی نیست و workflow عمومی refund وجود ندارد. قیمت منتشرشده و مبلغ محاسبه‌شده مقدار عملیاتی پیش از مالیات است، نه invoice، مبلغ settlement، رکورد مالیاتی، رکورد revenue recognition یا حساب قانونی. GET /v1/usage فقط token است و صورت‌حساب مشتری نیست.

خطاها

شکست HTTP از envelope پایدار دارای type، code، message_key، message_args، param، retryable و request_id استفاده می‌کند. فقط message محلی‌سازی می‌شود.

Status	کد رایج	قابل retry
400	invalid_request یا unsupported_parameter	خیر
401	invalid_api_key	خیر
402	insufficient_credit	خیر
403	forbidden	خیر
409	idempotency_conflict	خیر
429	rate_limit_exceeded	بله
503	model_unavailable	بله

متن محلی‌شده message را parse نکنید. براساس status HTTP و code تصمیم بگیرید، request_id را برای پشتیبانی نگه دارید و از retryable و در صورت وجود Retry-After پیروی کنید. خطای عمومی نام provider، خطای خام provider، credential، محتوای prompt یا topology داخلی ندارد.

نگه‌داری امن کلید

• کلید تازه را فقط یک‌بار کپی و در secret manager تأییدشده ذخیره کنید.
• کلید را در environment variable یا فایل secret mount‌شده قرار دهید و هرگز hard-code نکنید.
• کلید را در URL، browser storage، frontend bundle، source، screenshot، log یا پیام پشتیبانی نگذارید.
• فقط scopeهای لازم برنامه را انتخاب کنید.
• اگر احتمال exposure وجود دارد، کلید را فوراً revoke و با کلید تازه جایگزین کنید.