接口一览

01鉴权与约定

Base URL: https://api.456.com.cn
Authorization: Bearer <API_KEY>
Content-Type: application/json

• 金额一律以微元（1 元 = 1e6）给整数，另给展示串；展示串不要参与运算。
• 时间为 ISO 8601 UTC。
• 写操作支持 Idempotency-Key 头，同键返回同一任务、不重复计费。
• 速率限制超出时返回 429 并带 Retry-After。

02端点

创建任务的请求体

H3 不支持反向提示词，请勿依赖旧字段 negative_prompt。控制台高级参数的可见性和默认值由管理后台配置；Context IR 在提示词下方单独选择，账户可保存其默认状态。

任务返回

下例为 5 秒 768P 标准档、未开启 Context IR 的成功任务，按当前价格合计 ¥0.45；完整价目可通过 GET /v1/pricing 查询。

{
  "id": "vid_...",
  "object": "video.task",
  "status": "succeeded",
  "progress": 1,
  "mode": "text_to_video",
  "resolution": "768p",
  "duration": 5,
  "created_at": "...", "started_at": "...", "completed_at": "...",
  "accelerated": true,
  "output": {
    "video_uri": "...", "width": 1344, "height": 768,
    "duration": 5, "has_audio": true, "watermarked": true,
    "expires_at": "..."
  },
  "usage": { "billed_seconds": 5, "amount_micro": 450000, "amount": "0.45", "currency": "CNY" }
}

已有作品超分到 2K

仅支持自己已完成且原视频仍可读取的 768P 作品。先调用 GET /v1/videos/{id}/upscale 获取报价；返回中的 amount_micro 必须原样提交。报价按原视频实际时长计算。

# 1) 获取报价，读取响应 amount_micro
curl $H3_BASE/v1/videos/vid_xxx/upscale -H "Authorization: Bearer $H3_API_KEY"

# 2) 将 AMOUNT_MICRO 替换为上一步返回的整数
curl -X POST $H3_BASE/v1/videos/vid_xxx/upscale \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_micro": AMOUNT_MICRO}'

创建成功返回 202 和新任务。若返回 existing，表示已有进行中或完成的超分任务，直接使用该任务。价格变化会返回 409，需重新获取报价。

超分保留原作品，只收超分阶段费用，不重复收基础生成、编码器和素材费。2K、4K 作品不支持再次调用此入口。

03素材

POST /v1/files 以 multipart 上传，purpose 取input_image（起始帧）、end_image（结束帧） 或 reference（参考素材）。返回含 expires_at；过期后字节会被真正删除，此后再以该文件创建任务将被拒绝。

reference 收三类：图（png/jpeg/webp）、视频（mp4/mov）、音频（mp3/wav/m4a/flac）。 上传时平台会从容器头里读出时长（视频、音频）与像素尺寸（图、视频）—— 前者是计费与 15 秒累计闸的依据， 后者给 aspect_ratio: "auto" 用。音频读不出时长会被 400 拒：15 秒时长限制以该元数据为唯一依据， 接受无法解析时长的文件将使该限制失效。

⚠️ 参考视频会被模型截断到成片帧数：出 5 秒片时， 一段 15 秒的参考视频只有前 5.17 秒进得去（帧数还要向下对齐到 17k+5 栅格）。 这不是平台的选择，是模型本身的行为（ComfyUI 节点里的硬截断，没有开关）。但计费按你上传的时长算 —— 字节我们全都收下、存下、要传给编码器， 成本在上传那一刻就发生了。想让整段素材都生效，把 duration调到不小于素材时长。

03b旧版提示词优化接口

任务页已移除此按钮。现在可通过 use_context_ir 选择官方 Context IR；下面保留旧接口的对接说明。

POST /v1/prompt/optimize，请求体 { "prompt": "…" }， 返回优化后的 prompt（可直接填进创建任务请求）。按次计费，单价见 GET /v1/pricing 的 prompt_opt_micro，不要在客户端写死价格。

三条与钱有关的行为：余额不足返回 402 且不扣费； 优化服务出错返回 502 且不扣费；只有成功返回时才扣一笔，在流水里记作 prompt_optimize。 这一笔不挂在任何任务上 —— 你可以优化完不发任务。

04余额

GET /v1/credits 返回余额与近期流水。权威余额是流水求和；返回中的余额快照仅供对账参考，并发写入下可能不是最新值。

05API Key

列表只返回掩码。创建时明文只出现一次，平台仅存哈希 —— 丢了只能吊销重建。

06任务状态机

07错误结构

{
  "error": {
    "type": "invalid_request_error",
    "code": "task_not_cancellable",
    "message": "…",
    "param": "duration",
    "request_id": "req_..."
  }
}

反馈问题时请附上 request_id。各状态码的含义见错误码。