异步任务

图片、视频、音频等生成类模型都以异步任务方式调用：提交后立即拿到任务编号，生成完成后通过查询或 Webhook 取回结果。

提交任务

POSThttps://api.miaozuo.cn/v1/tasks

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <API Key>`，见鉴权与签名
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	幂等键，1～64 个可见字符，建议用你的业务单号，见下文幂等提交

请求体

字段	类型	必填	说明
`model`	string	是	模型编码，见模型列表
`input`	object	是	模型参数（也可以写成 `params`）。字段、类型、取值范围由各模型文档页的参数表定义（与 `GET /v1/models/{id}` 返回的 `params_schema` 一致），不合法时返回 422 `invalid_params`，`details` 里逐个字段说明原因
`webhook_url`	string	否	任务结束时回调的地址，必须是 HTTPS、不能是内网地址；不填则使用开放平台里设置的默认地址，见 Webhook 回调
`metadata`	object	否	自定义键值对，原样出现在查询结果、列表和回调里，便于关联你的业务数据。最多 16 个键，键 1～64 个字符，值为字符串（最多 512 个字符）

请求体示例

{
  "model": "qwen-image-3.0",
  "input": {
    "prompt": "一只戴宇航员头盔的橘猫，蓝色星空背景",
    "ratio": "1:1",
    "count": 1
  },
  "webhook_url": "https://<你的域名>/miaozuo/webhook",
  "metadata": {
    "order_id": "1001"
  }
}

受理成功返回 HTTP 200 和任务对象，状态为 queued，所需点数已冻结。提示词或参考素材未通过内容审核、参数错误、点数不足等情况会直接返回错误，不创建任务、不扣点。各模型的完整请求示例见对应的模型文档。

幂等提交

同一账号下，相同的 Idempotency-Key 只会创建一个任务、只冻结一次点数。幂等键长期有效，不会过期复用。
重复提交且模型和参数（按参数表规范化后）都相同时，返回第一次创建的任务，响应头带 Idempotent-Replayed: true。
幂等键相同但模型或参数不同时返回 409 idempotency_conflict，不创建任务。
网络超时等不确定结果的情况，用同一个幂等键重试即可，不会重复扣点。

查询任务

GEThttps://api.miaozuo.cn/v1/tasks/{id}

只能查询本账号创建的任务，别人的任务一律返回 404 not_found。查询不扣点，但计入 Key 的每分钟请求数。

curl https://api.miaozuo.cn/v1/tasks/T261009170328CGM0GT \
  -H "Authorization: Bearer $MIAOZUO_API_KEY"

任务对象

提交、查询、列表、取消接口和 Webhook 回调的 data 返回的都是同一个任务对象。

字段	类型	说明
`id`	string	任务编号，形如 `T261009170328CGM0GT`
`object`	string	固定为 `task`
`model`	string	模型编码
`status`	string	任务状态，见任务状态
`created_at` / `started_at` / `finished_at`	string \| null	提交、开始生成、结束时间；未发生时为 `null`
`input`	object	规范化后的参数：补齐了默认值、去掉了与当前选项无关的字段，计价就按它算
`points`	object	冻结、实扣、退回点数（`frozen` / `charged` / `refunded`，三位小数字符串），见计费与点数
`output`	object \| null	成功时的结果，其他状态为 `null`，字段见下表
`error`	object \| null	失败或取消的原因：`code`（字符串，见任务失败原因）、`message`；其他状态为 `null`
`metadata`	object	提交时传入的自定义键值，没有时为 `{}`

output 字段

字段	说明
`files`	结果文件列表，每项：`url`、`type`（image / video / audio / file 等）、`mime_type`、`size`（字节）、`width` / `height`（图片、视频）、`duration`（音视频秒数）、`cover_url`（视频封面）、`expires_at`；不适用的字段为 `null`
`text`	文本类结果（如文案、识别结果）才有
`voice_id`	声音复刻类模型才有：生成的音色编号，可填进语音合成模型的音色参数
`duration`	按时长计费的结果才有：实际时长（秒）
`usage`	按用量计费的结果才有：实际用量明细

成功示例

{
  "id": "T261009170328CGM0GT",
  "object": "task",
  "model": "qwen-image-3.0",
  "status": "succeeded",
  "created_at": "2026-10-09T17:03:28+08:00",
  "started_at": "2026-10-09T17:03:29+08:00",
  "finished_at": "2026-10-09T17:03:32+08:00",
  "input": {
    "prompt": "一只戴宇航员头盔的橘猫，蓝色星空背景",
    "ratio": "1:1",
    "resolution": "1k",
    "count": 1,
    "smart_prompt": true
  },
  "points": {
    "frozen": "33.000",
    "charged": "33.000",
    "refunded": "0.000"
  },
  "output": {
    "files": [
      {
        "url": "https://api.miaozuo.cn/ai/202610/104a3f61ba496027e7aebd892ec2fc86.png",
        "type": "image",
        "mime_type": "image/png",
        "size": 66589,
        "width": 1024,
        "height": 1024,
        "duration": null,
        "cover_url": null,
        "expires_at": "2026-11-08T17:03:32+08:00"
      }
    ]
  },
  "error": null,
  "metadata": {
    "order_id": "1001"
  }
}

失败示例

{
  "id": "T261009171205K8Q2MD",
  "object": "task",
  "model": "qwen-image-3.0",
  "status": "failed",
  "created_at": "2026-10-09T17:12:05+08:00",
  "started_at": "2026-10-09T17:12:06+08:00",
  "finished_at": "2026-10-09T17:12:19+08:00",
  "input": {
    "prompt": "一只戴宇航员头盔的橘猫，蓝色星空背景",
    "ratio": "1:1",
    "resolution": "1k",
    "count": 1,
    "smart_prompt": true
  },
  "points": {
    "frozen": "33.000",
    "charged": "0.000",
    "refunded": "33.000"
  },
  "output": null,
  "error": {
    "code": "content_rejected",
    "message": "生成结果未通过内容安全审核，未交付，点数已退回"
  },
  "metadata": {}
}

任务状态

状态	含义	终态
`queued`	已受理并冻结点数：输入审核中或排队等待生成	否
`processing`	生成中，包括提交、生成、结果审核与文件处理	否
`succeeded`	成功。结果文件已存入秒做存储，按结算规则扣点，多冻结的部分退回	是
`failed`	失败（参数、内容审核、超时或服务异常），冻结的点数全额退回	是
`canceled`	已取消（调用取消接口），冻结的点数全额退回	是

状态按 queued → processing → succeeded / failed 推进；queued 也可能直接变为 failed 或 canceled。超过模型的最长处理时间（见各模型文档）仍未完成的任务按失败处理，点数全额退回。

任务失败原因

任务失败或取消时，任务对象的 error.code 为以下之一（这不是 HTTP 错误，查询接口本身返回 200）：

error.code	说明	处理建议
`invalid_params`	参数不符合要求，请调整后重试（已退回点数）	修正参数后重新提交
`content_rejected`	内容未通过安全审核，请修改描述后重试（已退回点数）	修改提示词或素材后重新提交
`insufficient_points`	点数不足，任务未开始，未扣点	充值后重新提交
`timeout`	生成超时，已自动退回点数，请稍后重试	稍后重新提交
`service_unavailable`	该模型暂不可用，已自动退回点数	稍后重新提交，或换一个模型
`capacity_shortage`	平台算力暂时不足，已自动退回点数，请稍后再试	稍后重新提交
`generation_failed`	生成失败，已自动退回点数，请稍后重试	稍后重新提交
`no_result`	没有找到相关内容，换个链接或关键词再试试（已退回点数）	检查链接、编号或换个关键词后重新提交
`canceled`	任务已取消，点数已退回	无需处理

轮询建议

优先使用 Webhook，收到回调后再查询一次确认结果。
需要轮询时，首次间隔不少于 3 秒，之后逐步拉长，最长 30 秒一次。
拿到 succeeded、failed 或 canceled 后停止轮询。

任务列表

GEThttps://api.miaozuo.cn/v1/tasks

列出本账号通过开放 API 和开放平台在线测试提交的任务，最近的在前（网页创作的任务不在其中）。

查询参数	说明
`status`	可选，按状态筛选：`queued` / `processing` / `succeeded` / `failed` / `canceled`
`model`	可选，按模型编码筛选
`limit`	每页条数，默认 20，最大 100
`page`	页码，从 1 开始

cURL

# 最近的在前；status、model 可选，limit 默认 20、最大 100
curl "https://api.miaozuo.cn/v1/tasks?status=succeeded&limit=20&page=1" \
  -H "Authorization: Bearer $MIAOZUO_API_KEY"

返回示例

{
  "object": "list",
  "data": [
    { …任务对象… }
  ],
  "page": 1,
  "limit": 20,
  "has_more": false
}

取消任务

POSThttps://api.miaozuo.cn/v1/tasks/{id}/cancel

还在排队或输入审核中的任务可以直接取消，状态变为 canceled，冻结的点数全额退回，返回任务对象。
已开始生成的任务大多不能取消；已结束的任务不能取消。不能取消时返回 409 task_not_cancelable，message 说明原因。

cURL

curl -X POST https://api.miaozuo.cn/v1/tasks/T261009170328CGM0GT/cancel \
  -H "Authorization: Bearer $MIAOZUO_API_KEY"

不能取消时

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "task_not_cancelable",
    "message": "任务已结束，不能取消",
    "request_id": "req_qg1myspuhvduzuolvoaj5m9g"
  }
}

结果文件与保留期

结果文件存放在秒做存储，地址形如 https://api.miaozuo.cn/…，文件名为不可猜测的随机串。
开放 API 生成的结果文件有保留期，具体以每个文件的 expires_at 为准。到期后文件删除、地址失效，请及时下载到自己的存储。
结果文件按规定添加 AI 生成内容标识。
需要传参考图、音频、视频时，先用文件上传拿到地址，再填进参数。