# شروع سریع

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

> [!NOTE]
> نشانی پایه `https://api.doitong.com/v1` است. هر فراخوانی `Authorization: Bearer <your key>` را ارسال می‌کند و همین کلید برای HTTP API و سرور MCP کار می‌کند.

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

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

```bash
export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.com/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` },
});

console.log(await res.json());
```
```python
import os
import requests

r = requests.get(
    "https://api.doitong.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

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

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

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

```bash
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}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "https://example.com/fox.jpg", duration: 5, generate_audio: true }),
});

const quote = await res.json();
console.log(quote.credits, quote.usd); // 840 "0.84"
```
```python
import requests

r = requests.post(
    "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video",
    json={"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": True},
)
print(r.json()["credits"], r.json()["usd"])  # 840 0.84
```

```json 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` را ارسال کنید تا تلاش مجدد هرگز اجرا را دوباره انجام ندهد (یا هزینه دوباره‌ای ایجاد نکند).

```bash
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"}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/run/flux/schnell?wait=20", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOITONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "lighthouse-001",
  },
  body: JSON.stringify({ prompt: "A lighthouse on a rocky coast at dusk, warm light in the window" }),
});

const request = await res.json();
console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

r = requests.post(
    "https://api.doitong.com/v1/run/flux/schnell",
    params={"wait": 20},
    headers={
        "Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}",
        "Idempotency-Key": "lighthouse-001",
    },
    json={"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"},
)
request = r.json()
print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

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

```json 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` فعلی آن دریافت می‌کنید. هر درخواست چرخه حیات یکسانی را طی می‌کند:

چرخه عمر درخواست: `queued` → `running` → `succeeded` | `failed` | `canceled` (نهایی؛ درخواست‌های ناموفق و لغوشده بازپرداخت می‌شوند).

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

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const headers = { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` };
let request = await (await fetch("https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.com/v1/requests/${request.id}?wait=20`, { headers });
  request = await res.json();
}

console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"}
request = {"id": "req_8k2m4q7x1z9c3v5b6n0p2r4t", "status": "queued"}

while request["status"] in ("queued", "running"):
    request = requests.get(
        f"https://api.doitong.com/v1/requests/{request['id']}",
        params={"wait": 20},
        headers=headers,
    ).json()

print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

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

```bash
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

برای کارهای طولانی ویدیویی می‌توانید از نظرسنجی صرف‌نظر کنید و به‌جای آن `webhook_url` را ارسال کنید (به [وب‌هوک‌ها](https://doitong.com/developers/docs/webhooks) مراجعه کنید).

## ۴. فایل‌ها

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

```bash
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}'
```

> [!TIP]
> **فایل‌ها برای همیشه نگه‌داری شوند، یا ۷ روز رایگان: انتخاب با شماست.** فایل‌های خروجی پیش از موفق شدن درخواست در فضای ذخیره‌سازی ما کپی می‌شوند. به‌طور پیش‌فرض تا زمانی که آن‌ها را حذف کنید باقی می‌مانند (۱۰۰ اعتبار API به‌ازای هر GB در ماه)؛ گزینه «فایل‌ها برای همیشه نگه داشته شوند» را در داشبورد خاموش کنید، یا `?storage=temporary` را ارسال کنید تا برای ۷ روز رایگان نگه‌داری شوند (به [فایل‌ها](https://doitong.com/developers/docs/files#storage) مراجعه کنید).

## خطاها

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

```json 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"
  }
}
```

هر نوع و کد در [خطاها](https://doitong.com/developers/docs/errors) فهرست شده است.

## قیمت‌گذاری

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

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

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

```bash 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/models) را مرور کنید. هر صفحه یک سازنده درخواست دارد که کد را برای شما می‌نویسد.
- چرخه حیات درخواست را یاد بگیرید: [درخواست‌ها](https://doitong.com/developers/docs/requests).
- در همه مدل‌ها از نام پارامترهای یکسان استفاده کنید: [پارامترها](https://doitong.com/developers/docs/parameters).
- با یک عامل کدنویسی هوش مصنوعی کار می‌کنید؟ [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) را در اختیارش بگذارید یا [سرور MCP](https://doitong.com/developers/docs/mcp) را متصل کنید.