鉴权与限流

鉴权

所有请求都要在请求头中带上 API Key：

Authorization: Bearer sk-你的Key

• 每个账号最多创建 20 个 Key。
• 可为 Key 设置 IP 白名单，设置后只有白名单中的 IP 可以使用。
• Key 泄露时，请立即在控制台禁用或删除。

Key 无效、禁用或过期时返回 401。

限流

限制	默认值	超出时返回
每个 Key 每分钟请求数	60	429 rate_limited
同时进行中的任务数	5	429 concurrency_limited

查询任务也计入每分钟请求数。收到 429 后请稍后重试。

Idempotency-Key

创建任务时建议在请求头中带上你的业务 ID。它必须是最长 128 位的 ASCII 字符串，例如订单号或 UUID；不要在 HTTP Header 中使用中文：

Idempotency-Key: order_10086

• 查询任务和 Webhook 推送中会以 idempotency_key 字段原样返回，用于对应你的业务记录。
• 同一功能内不能重复。重复提交时返回原任务，不会重复生成，请求体中的参数也不会生效。
• 请求超时不确定是否创建成功时，原样重发请求即可。
• 原任务失败后，可以用同一个值重新提交，此时会创建新任务。

请求 ID

每个响应头都带有 X-Request-Id。反馈问题时请提供它。