رفتن به محتوا
شروع کار

شروع سریع

نمایش به‌صورت Markdown به‌روزرسانی‌شده

اولین تولید خود را در چند دقیقه اجرا کنید. هر ۱٬۴۹۶ مدل، برای تصویر، ویدیو و صوت، همین نوع درخواست را می‌گیرد و همان شیء درخواست را برمی‌گرداند: این الگو را فقط یک‌بار یاد بگیرید.

۱. دریافت کلید API

در https://doitong.com/developers/dashboard#keys یک کلید بسازید و آن را در یک متغیر محیطی نگه دارید: این کلید فقط یک‌بار نمایش داده می‌شود. هر کلید می‌تواند بودجه مخصوص خودش را داشته باشد، بنابراین می‌توانید آن را بدون به خطر انداختن کل حساب در اختیار یک عامل بگذارید. GET /account موجودی API شما را برمی‌گرداند.

export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.com/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

اجراها از موجودی API حساب شما، برحسب اعتبار API، پرداخت می‌شوند: ۱٬۰۰۰ اعتبار API = ⁨‎$۱⁩؛ و هزینه هر مدل دقیقاً برابر قیمت سازنده آن است. موجودی را در https://doitong.com/developers/dashboard#balance افزایش دهید.

۲. دریافت قیمت، سپس اجرا

POST /quote/{model_id} JSON ورودی را می‌گیرد و قیمت دقیق را برمی‌گرداند. به کلید نیاز ندارد و هزینه‌ای ندارد. اجرای همان ورودی دقیقاً همین مقدار هزینه دارد: قیمت اعلام‌شده همان مبلغ کسرشده است. (مدلی که بر اساس مصرف هزینه می‌گیرد، استثناست: قیمت اعلام‌شده حداکثر هزینه اجرای آن است و بخش استفاده‌نشده پس از اجرا بازپرداخت می‌شود.)

curl -X POST "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": true}'
200 OK · قیمت
{
  "object": "quote",
  "model": "kling-video/v3/pro/image-to-video",
  "credits": 840,
  "usd": "0.84",
  "unit": "second",
  "quantity": 5,
  "unit_credits": 168,
  "mode": "exact",
  "breakdown": "5 s × 168 API credits"
}

سپس همان بدنه را به POST /run/{model_id} ارسال کنید. برای نگه‌داشتن اتصال تا ۲۰ ثانیه، ?wait=20 را اضافه کنید: یک مدل سریع، نتیجه نهایی را در یک رفت‌وبرگشت برمی‌گرداند. هدر Idempotency-Key را ارسال کنید تا تلاش مجدد هرگز اجرا را دوباره انجام ندهد (یا هزینه دوباره‌ای ایجاد نکند).

curl -X POST "https://api.doitong.com/v1/run/flux/schnell?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"}'

پاسخ یک شیء درخواست است:

200 OK · درخواست
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg", "width": 1024, "height": 768, "stored": true }
  ],
  "error": null
}

۳. پیگیری وضعیت

اگر با پایان زمان انتظار، مدل هنوز در حال کار باشد، پاسخ 202 Accepted را همراه با id درخواست و status فعلی آن دریافت می‌کنید. هر درخواست چرخه حیات یکسانی را طی می‌کند:

چرخه عمر درخواست
  1. queued پذیرفته و هزینه آن دریافت شده؛ در انتظار کارگر
  2. running مدل در حال تولید است
  3. وضعیت‌های نهایی:
    • succeededهزینه اعلام‌شده دریافت شد؛ outputs[] شامل URLهای فضای ذخیره‌سازی ماست
    • failedبه‌صورت خودکار بازپرداخت شد؛ خطا دلیل را نشان می‌دهد
    • canceledپیش از نتیجه متوقف شد؛ بازپرداخت شد

درخواست را دوباره با شناسه آن بخوانید. ?wait=20 اینجا هم کار می‌کند، بنابراین یک حلقه ساده کافی است:

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

وقتی status برابر succeeded باشد، outputs[].url پیوندهای فایل‌ها را در فضای ذخیره‌سازی ما نگه می‌دارد. اگر درخواست failed یا canceled شود، اعتبار API آن به‌طور خودکار بازپرداخت می‌شود و error دلیل را اعلام می‌کند. هر چیزی را که هنوز queued یا running است لغو کنید:

ترمینال
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

برای کارهای طولانی ویدیویی می‌توانید از نظرسنجی صرف‌نظر کنید و به‌جای آن webhook_url را ارسال کنید (به وب‌هوک‌ها مراجعه کنید).

۴. فایل‌ها

هر URL عمومی را به‌عنوان ورودی ارسال کنید، یا از POST /files یک URL بارگذاری بخواهید، فایل را با PUT در آن قرار دهید و از file_url برگشتی استفاده کنید (به فایل‌ها مراجعه کنید). یک درخواست موفق، نتایج خود را در outputs[] همراه با نوع، نوع محتوا و، در صورت مشخص بودن، ابعاد و مدت‌زمان فهرست می‌کند.

ترمینال
curl -X POST "https://api.doitong.com/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'

خطاها

هر مدل به یک شکل خطا می‌دهد: یک پوشش شامل type، یک code دقیق، param مشکل‌دار و هر مشکل در details؛ بنابراین یک عامل می‌تواند درخواست را بدون خواندن متن توضیحات اصلاح کند. بابت درخواست نامعتبر چیزی کسر نمی‌شود.

422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}

هر نوع و کد در خطاها فهرست شده است.

قیمت‌گذاری

قیمت‌ها به USD و اعتبار API هستند و پیش از اجرا در صفحه هر مدل نمایش داده می‌شوند. هر درخواست شامل cost با credits، usd، charged و refunded است. هزینه اجرا هنگام پذیرش آن کسر می‌شود؛ درخواست‌های failed و canceled به‌طور خودکار بازپرداخت می‌شوند. قیمت بعضی مدل‌ها دقیقاً از ورودی محاسبه می‌شود، بعضی بر اساس طول یا اندازه فایل‌هایی که ارسال می‌کنید، و بعضی دیگر قیمت تخمینی به‌ازای هر اجرا دارند: در هر صورت، مبلغ اعلام‌شده همان مبلغی است که می‌پردازید. چند مدل (مدل‌های زبانی و بینایی، صوت و ابزارهای زمان پردازش) بر اساس مصرف هزینه‌گذاری می‌شوند: قیمت اعلام‌شده حداکثر هزینه اجراست و بخشی که اجرا استفاده نکرده است به‌طور خودکار بازپرداخت می‌شود. به قیمت‌گذاری مراجعه کنید.

MCP و عوامل هوش مصنوعی

هر کلاینت MCP را با همان کلید Bearer به https://api.doitong.com/v1/mcp متصل کنید. عامل شما می‌تواند کاتالوگ را جست‌وجو کند، قیمت مدل‌ها را بگیرد و آن‌ها را اجرا کند و همه صفحات مستندات را به‌صورت Markdown بخواند.

Claude Code
claude mcp add --transport http doitong-models https://api.doitong.com/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

گام‌های بعدی

  • همه مدل‌ها را مرور کنید. هر صفحه یک سازنده درخواست دارد که کد را برای شما می‌نویسد.
  • چرخه حیات درخواست را یاد بگیرید: درخواست‌ها.
  • در همه مدل‌ها از نام پارامترهای یکسان استفاده کنید: پارامترها.
  • با یک عامل کدنویسی هوش مصنوعی کار می‌کنید؟ https://doitong.com/developers/llms.txt را در اختیارش بگذارید یا سرور MCP را متصل کنید.