AI STUDIO / OPENAPI V1

本站中转接口文档

使用本站账户的 API Key 调用视频生成接口，费用从本站积分余额结算。模型规格和售价以实时模型接口返回为准。

接口地址https://ai.zhaochenpi.com/openapi/v1http://ai.zhaochenpi.com/openapi/v1两种协议均可直接调用，不会从 HTTP 跳转到 HTTPS。HTTP 会明文传输 API Key，建议优先使用 HTTPS。

1. 获取密钥与鉴权

登录工作台，在「账户与账单 → 本站 API Key」填写密钥名称并点击创建。新密钥的明文保存在数据库中，登录后可在密钥列表再次查看和复制。升级前创建的旧密钥只存哈希，无法恢复明文；请创建新密钥，完成接入切换后再停用旧密钥。

Authorization: Bearer relay_live_你的完整密钥

密钥属于当前用户，只能查询和使用该用户的积分、素材和任务。请勿在前端网页或公开代码中放入完整密钥。此密钥是本站密钥，不是上游 KOKO / wutuobang 密钥。

2. 查询模型与价格

GET/models返回可用模型、时长、比例、分辨率及本站积分售价。

GET/account返回总积分、冻结积分和可用积分。

curl -H "Authorization: Bearer 你的完整密钥" \
  https://ai.zhaochenpi.com/openapi/v1/models

curl -H "Authorization: Bearer 你的完整密钥" \
  https://ai.zhaochenpi.com/openapi/v1/account

模型响应中的 models[].id 用作生成请求的 model；duration_prices 是按时长区分的本站售价。enabled=false 或 maintenance=true 的模型不可提交。账户响应中的 balance 为可用积分，reserved 为已冻结积分，total_balance 为账户总积分。

3. 创建视频

POST/videos成功接受请求返回 HTTP 202 和本站任务 ID。

每次新任务都要提供唯一的 Idempotency-Key，长度 8–90，只能包含字母、数字、下划线和横线。网络超时后，使用相同编号和相同参数重试，避免重复冻结积分或重复生成。也可以在 JSON 中使用 request_id。

curl -X POST https://ai.zhaochenpi.com/openapi/v1/videos \
  -H "Authorization: Bearer 你的完整密钥" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my_video_20261013_001" \
  -d '{
    "model": "minimaxh3",
    "prompt": "清晨的产品特写，镜头缓慢推进",
    "duration": 5,
    "ratio": "9:16",
    "resolution": "2K",
    "mode": "text-to-video"
  }'

示例规格只用于说明格式。实际请求前先查询 /models，使用当前模型返回的 id、durations、ratio 和 resolutions。prompt 必填；count 只能为 1。duration、ratio、resolution 未填时会使用模型默认值。建议额外提供 max_points 作为本次允许的最高售价，防止价格变化时超出预期。

mode 支持 text-to-video（纯文字）、reference（至少一张参考图）和 first-frame（恰好一张首帧图）。

4. 查询任务与下载

GET/videos/{本站任务ID}查询生成、计费和 COS 归档状态。

GET/videos/{本站任务ID}/content完成归档后返回 307，跳转到临时 COS 下载地址。

curl -H "Authorization: Bearer 你的完整密钥" \
  https://ai.zhaochenpi.com/openapi/v1/videos/本站任务ID

status 可能为 submitting、queued、running、completed、failed。只有 status=completed 且 storage_state=ready 才表示视频已归档，可以读取响应中的临时 video_url 或请求 /content。storage_state=error 表示归档待后台重试，不代表需要重新生成。

下载接口需要本站密钥；跳转后的 COS 地址是临时签名地址，访问 COS 时不要再发送本站 Authorization 请求头。临时地址过期后重新查询原任务即可。

5. 参考素材

可在创建请求的 attachments 中直接传公网 HTTPS 链接，也可以先上传文件到本站 COS，再传返回的 asset_id。上传接口地址为 POST /api/assets/upload（位于网站根路径的 /api 下），表单字段名为 file，同样使用本站密钥鉴权。

curl -X POST https://ai.zhaochenpi.com/api/assets/upload \
  -H "Authorization: Bearer 你的完整密钥" \
  -F "file=@reference.jpg"

"attachments": [{"type":"image","asset_id":"上传响应中的id"}]

外部图片示例：{"type":"image","url":"https://example.com/image.jpg"}。首帧模式只能添加一张图片；文生视频不接受素材。素材数量和类型受所选模型限制。外部参考视频需要提供 duration_seconds；本地上传的视频由服务端自动识别时长。

6. 计费、失败与限制

本站售价为上游积分价格的 2 倍。创建任务时先冻结预计积分；成功后按实际费用结算，明确失败后解冻。创建接口返回任务后，后台继续处理，关闭网页不会取消任务。

接口错误使用 HTTP 状态码并返回 {"error":{"code":"...","message":"..."}}。常见情况包括 401 密钥无效、402 积分不足、409 幂等参数冲突或价格变化、429 请求过频、503 服务暂不可用。提交结果不确定时沿用原幂等编号查询或重试，不要换新编号。

本站接口与上游接口文档分开：客户端只需使用本站密钥和上述本站地址，无需接触运营者的上游密钥。