公共参数

所有 /v1 接口共用的约定：接口地址、请求头、响应头、数值与时间格式、分页、限速与并发。

接口地址

接口基址	`https://api.miaozuo.cn/v1`
协议	HTTPS。请求与返回都是 JSON（UTF-8）；上传文件的 `POST /v1/files` 另外支持 `multipart/form-data`。
鉴权	`Authorization: Bearer sk-…`，见鉴权与签名

请求头

请求头	是否必填	说明
`Authorization`	必填	`Bearer <API Key>`。`POST /v1/messages` 也可以改用 `x-api-key` 头。
`Content-Type`	有请求体时必填	`application/json`；上传文件时为 `multipart/form-data`。
`Idempotency-Key`	可选	仅 `POST /v1/tasks`。1～64 个可见字符（字母、数字、符号），建议用你的业务单号。同一账号下同一个键只会创建一个任务，长期有效，详见幂等提交。
`X-Mz-Timestamp` `X-Mz-Nonce` `X-Mz-Signature`	Key 开启签名时必填	见请求签名。

响应头

响应头	说明
`X-Request-Id`	每个 `/v1` 响应都有，形如 `req_` 加 24 位小写字母和数字；出错时与错误体里的 `request_id` 相同。排查问题或联系客服时请提供它。
`Idempotent-Replayed`	值为 `true` 时表示这次请求命中了已有的幂等键，返回的是第一次创建的任务，没有重复扣点。
`Retry-After`	触发每分钟请求数限制（429 `rate_limited`）时返回，单位秒，表示多久后可以重试。

数值与时间

点数一律是保留三位小数的字符串，如 "33.000"、"0.150"，请按十进制处理，不要转成浮点数再做加减。
时间一律是 ISO 8601 格式的北京时间，如 2026-10-09T17:03:28+08:00；未发生的时间为 null。
编号：任务 T261009170328CGM0GT（T + 时间 + 6 位），文件 file_43，文本调用 mzchat_… / mzresp_… / mzmsg_…。
结果文件地址都是秒做的文件地址，带有效期（expires_at），请在到期前转存到你自己的存储。

分页

列表接口（如 GET /v1/tasks）用 page（从 1 开始）和 limit（默认 20，最大 100）翻页，返回：

列表返回

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

has_more 为 true 时把 page 加 1 继续取。

限速与并发

限制	范围	超出时
每分钟请求数	按 Key 计数，可在开放平台为每个 Key 单独设置；不设置时使用平台默认值	429 `rate_limited`，带 `Retry-After`
Key 并发数	这个 Key 进行中的任务与文本调用数，可在开放平台单独设置	429 `concurrency_limited`
账户并发数	整个账户同时进行中的生成任务、文本调用数，会员档位、渠道等级越高上限越高	429 `concurrency_limited`

被限速、限并发拦下的请求不创建任务、不扣点。建议收到 429 后按 Retry-After 或指数退避重试。

错误返回

HTTP 状态码非 2xx 时，返回统一的错误体，code 是字符串错误码，参数错误时多一个逐字段的 details。文本模型接口的错误体兼容各 SDK 的格式，见文本模型。完整错误码见错误码。

错误返回示例

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: req_xaw1zhb0bh6app6dnbxtq7yj

{
  "error": {
    "code": "invalid_params",
    "message": "画面描述不能为空",
    "request_id": "req_xaw1zhb0bh6app6dnbxtq7yj",
    "details": [
      {
        "field": "prompt",
        "message": "画面描述不能为空"
      },
      {
        "field": "ratio",
        "message": "画面比例不在可选范围内（可选：1:1、3:4、4:3、9:16、16:9）"
      }
    ]
  }
}

调用记录

所有 /v1 请求（包括被拦下的）都会记录，可在开放平台的调用记录里按 X-Request-Id 查询，保留 30 天。