# 快速入門

幾分鐘內執行您的第一次生成。所有 1,496 個模型都接受相同類型的請求，並針對圖像、影片和音訊回傳相同的請求物件：在這裡學會一次即可。

> [!NOTE]
> 基礎 URL `https://api.doitong.ru/v1`。每次呼叫都會傳送 `Authorization: Bearer <your key>`，相同的金鑰可用於 HTTP API 和 MCP 伺服器。

## 1. 取得 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.ru/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.ru/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.ru/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

執行費用會從您帳戶的 **API 餘額** 中以 API 點數支付：1,000 API 點數 = $1，每個模型的費用都恰好是其製作者設定的價格。在 [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) 儲值。

## 2. 先取得報價，再執行

`POST /quote/{model_id}` 接受輸入 JSON 並回傳確切價格。不需要金鑰，也不收費。使用相同輸入執行時，費用就正好是該報價：報價即為收費金額。（按用量計費的模型例外：其報價是該次執行可能產生的最高費用，未使用的部分會在執行完成後退款。）

```bash
curl -X POST "https://api.doitong.ru/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.ru/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.ru/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`，讓連線最多等待 20 秒：快速模型會在一次往返中回傳完成的結果。傳送 `Idempotency-Key` 標頭，確保重試不會執行（或收費）兩次。

```bash
curl -X POST "https://api.doitong.ru/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.ru/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.ru/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
}
```

## 3. 追蹤狀態

如果等待結束時模型仍在處理，您會收到 `202 Accepted`，其中包含請求的 `id` 和目前的 `status`。每個請求都會經歷相同的生命週期：

請求生命週期: `queued` → `running` → `succeeded` | `failed` | `canceled` (完成；失敗和已取消的請求會退款).

使用其 id 再次讀取請求。這裡同樣支援 `?wait=20`，因此簡單的迴圈就足夠：

```bash
curl "https://api.doitong.ru/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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.ru/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.ru/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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

對於長時間的影片工作，您可以略過輪詢，改為傳入 `webhook_url`（請參閱 [Webhooks](https://doitong.com/developers/docs/webhooks)）。

## 4. 檔案

您可以將任何公開 URL 作為輸入，或要求 `POST /files` 取得上傳 URL，將檔案 `PUT` 至該 URL，再使用回傳的 `file_url`（請參閱 [檔案](https://doitong.com/developers/docs/files)）。成功的請求會在 `outputs[]` 中列出結果，包括類型、內容類型，以及（若已知）尺寸和持續時間。

```bash
curl -X POST "https://api.doitong.ru/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'
```

> [!TIP]
> **檔案永久保存，或免費保存 7 天：由您選擇。** 輸出檔案會在請求成功前複製到我們的儲存空間。預設值是檔案會保留到您刪除為止（每 GB 每月 100 API 點數）；在控制面板中關閉「永久保存檔案」，或傳入 `?storage=temporary`，即可免費保留 7 天（請參閱 [檔案](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 和 AI 代理程式

使用相同的 Bearer 金鑰，將任何 MCP 用戶端連線至 `https://api.doitong.ru/v1/mcp`。您的代理程式可以搜尋目錄、取得報價並執行模型，也可以將所有文件頁面讀取為 Markdown。

```bash Claude Code
claude mcp add --transport http doitong-models https://api.doitong.ru/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)。
- 正在使用 AI 程式設計代理程式？提供 [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) 給它，或連線至 [MCP 伺服器](https://doitong.com/developers/docs/mcp)。