API 指南

请求

以 Markdown 查看更新时间 2026-10-22

一次请求就是对一个模型的一次调用。它包含一个 id（req_…）、状态、API 积分费用（1000 = 1 USD），以及在成功时生成的文件。以下每个端点对每个模型返回的都是同一个对象。

查找模型

包含全部 1,496 个模型的目录是公开 JSON（无需密钥）：

终端

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

查询参数	含义
`q`	必须全部出现在名称、id、制造商或标签中的词，例如 `kling 3`。
`category`	一个类别 id，例如 `text-to-video` 或 `upscale`。`GET https://api.doitong.com/v1/categories` 列出全部 21 个类别及其数量。
`lab`	模型的制造商，可按名称或 id 查询，例如 `Google` 或 `black-forest-labs`。
`family`	上一行中的 `family` id：同一模型的每个变体（pro、fast、image-to-video、…）。
`mode`	`exact`（根据输入计算价格）、`measured`（根据输入文件的长度或大小计算）、`estimate`（每次运行的预估价格）或 `metered`（按实际用量计费，每次运行不超过最大值）。
`limit`、`cursor`	页面大小（1 到 100，默认 50）以及上一页的 `next_cursor`。

每行包含 id、name、lab、category、family、summary、tags、output_kind、docs_url 和一个 price 对象（参见定价）。GET https://api.doitong.com/v1/models/{model_id} 还会返回完整的输入和输出 JSON Schema、规范参数名称、价格规则和示例输入。未知的 category 或 mode 会返回 400 invalid_parameter。

运行模型

终端

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

请求体是模型输入，即一个 JSON 对象。每个模型页面都会列出其参数。
输入会在收费前进行检查。无效输入会返回 422 invalid_input，并指出有问题的 param，且不会产生费用。
?wait=N（最多 20 秒）会保持调用，直到请求完成或超时。
?webhook_url=https://… 会在请求完成时向该 URL 发送带签名的 POST（参见 Webhook）。
?storage=permanent 或 ?storage=temporary 用于选择输出文件的保留时长；未指定时使用账户设置（参见文件存储位置）。

请求仍在处理时，响应为 202 Accepted；在等待时间内完成（或重放时，见下文）则为 200 OK。Location 和 Doitong-Request-Id 标头包含请求 URL 和 id。

状态

请求生命周期

queued 已接受并扣费，正在等待工作进程
running 模型正在生成
最终状态:
- succeeded已扣除报价金额；outputs[] 中包含我们存储空间的 URL
- failed已自动退款；错误信息说明了原因
- canceled在生成结果前停止；已退款

状态	含义	最终状态
`queued`	已接受并扣费，正在等待工作进程。`queue_position` 可能会显示队列中的位置。	否
`running`	模型正在生成。	否
`succeeded`	已完成。`outputs` 列出文件。	是
`failed`	模型或限制导致请求停止。`error` 说明原因。API 积分会退款。	是
`canceled`	在生成结果前取消。API 积分会退款。	是

运行时间超过时限的请求会失败并返回代码 timeout，同时退款：图像为 15 分钟，视频为 60 分钟，音频及其他内容为 30 分钟。

请求对象

JSON

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

对所有模型而言，outputs 的结构相同：每个生成文件对应一个条目，包含 type（image、video、audio、file 或 3d）、我们存储中的 url、content_type，以及已知时的 file_size、width、height、duration。
output 是模型自己的结果对象（其字段列在各模型页面上），其中包含相同的 URL。
storage 说明文件的保留方式：mode（permanent 或 temporary）、已存储的 bytes、expires_at（临时文件删除的时间，永久文件为 null）以及 expired（文件删除后为 true）。
cost.credits 是调用的 API 积分价格（cost.usd 以 USD 表示），cost.charged 是从 API 余额中扣除的金额，cost.refunded 是退回的金额。对于 metered 模型，cost.credits 是开始时预留的最大值（cost.held）；运行成功后，cost.settled 表示实际用量，其余最大值计入 cost.refunded（参见按用量计费）。
请求失败时，error 为 { "type": …, "code": …, "message": … }。

读取请求

终端

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

?wait=N（最多 20 秒）会进行长轮询：请求最终完成时立即返回，或在 N 秒后返回当前状态。这是等待结果最简单的方式。
?logs=1 会将模型的进度日志行（最近 50 行）作为 logs 添加。

你只能读取自己账户的请求；其他 id 会返回 404 request_not_found。

列出请求

终端

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

按最新优先。limit 为 1 到 100（默认 20），status 和 model 用于筛选。响应为 { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }；传递 cursor=<next_cursor> 获取下一页。

取消请求

终端

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

在模型启动前取消：状态变为 canceled，API 积分退款，并返回 200。
已在生成：取消请求会继续传递，并返回 202 以及 "cancel_requested": true。如果模型最终仍完成，请求会正常成功并收费。
已处于最终状态：返回 409 not_cancelable（已处于 canceled 状态的请求直接返回 200）。

删除请求的文件

终端

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

立即删除我们保存的请求输出文件，并停止其存储费用。响应是 storage.expired: true 的请求对象；其 URL 仍保留在记录中，但不再可用。再次调用不会产生变化（200）。仍处于 queued 或 running 状态的请求尚无文件：409 request_active。需要 models:run。

幂等性：重试且不会重复付费

网络可能会失败。要安全地重试运行，请发送 Idempotency-Key 标头（任意不超过 255 个字符的字符串，每个操作唯一，例如你自己的订单 id）：

与之前相同的密钥和请求体：返回原始请求（200，标头 Idempotent-Replayed: true），不会再次收费。
在运行于模型执行前失败（提交时出现 upstream_error 或 internal_error、insufficient_credits、budget_exceeded、too_many_inflight）后，使用相同的密钥和请求体：不会生成任何内容，也不会收费，因此重试会再次运行模型，而不是返回失败。
相同密钥但请求体不同：409 idempotency_mismatch。
密钥的作用域限定为发送它的 API 密钥。

文件存储位置

每个输出文件都会在请求标记为 succeeded 前复制到我们的存储中，因此 outputs 中的 URL 位于我们自己的主机上，你可以直接链接到这些 URL。文件保留多久由你决定：

模式	保留时长	价格
`permanent`（默认）	直到你删除它们	每 GB 每月 100 API 积分（$0.10），每天从 API 余额中扣费
`temporary`	7 天，之后删除	免费

账户设置决定新请求的默认值：控制面板中的“永久保留文件”开关，或使用 PATCH https://api.doitong.com/v1/account/storage 并传入 {"mode": "temporary"}。GET https://api.doitong.com/v1/account 会在 storage 下显示该设置、已保留的字节数和每月预估费用。
运行时的 ?storage=permanent|temporary（MCP run 工具的 storage 参数）会覆盖该运行的设置。
更改设置不会影响已有文件；请使用 DELETE /requests/{id}/files 删除这些文件。
API 余额无法支付存储费用时，不会扣费，你会收到电子邮件：请在 30 天内充值，否则保留的文件会变为临时文件，并在之后 7 天删除。

极少数情况下，如果我们的副本创建失败，条目会包含 "stored": false，URL 则是原始的短期 URL：请尽快下载。

查找模型#

运行模型#

状态#

请求对象#

读取请求#

列出请求#

取消请求#

删除请求的文件#

幂等性：重试且不会重复付费#

文件存储位置#