ZPod 视频生成 API 使用说明

通过文字或首帧图片生成视频。接口采用异步方式：获取 Token → 提交任务 → 查询状态 → 下载视频。网站与 API 共用账户余额。

网站入口：https://ai.zpod.net，接口基地址为 https://ai.zpod.net。

1. 开通与准备

1. 使用邮箱注册：输入两次相同密码，获取并填写 6 位邮箱验证码。验证成功后登录，进入“余额与账单”。验证码 10 分钟有效，60 秒后可以重发。
2. 提交充值订单，联系 Telegram @TgAiPayBot 取得收款方式；付款并经管理员确认后，余额到账。
3. 进入“开发者应用”，创建应用并保存 client_id 和 client_secret。密钥只展示一次。
4. 获取服务开通时提供的接口基地址，下文记为 API_BASE。将密钥仅保存在自己的后端。

所有费用以人民币计算。1 元 = 100 分（fen），接口金额字段使用整数分。

2. 价格与扣费

以上为初始价格，实际以网站价格和提交前的费用预估为准。文生与图生同价，音频不加价；按请求时长计费。

• 提交成功时冻结本次费用，避免余额被重复使用。
• 视频生成并可供下载后扣费；生成失败会退回冻结金额。
• 相同幂等键、相同参数的重复提交不会重复生成或重复收费。
• 生成完成后的主动重做属于新任务，单独收费；视频过期不退还已完成任务费用。

3. 获取 Token

POST /v1/oauth/token，请求类型为 application/json。

# 替换为服务开通时提供的基地址，在服务端配置应用凭证。
export API_BASE='https://ai.zpod.net'
export CLIENT_ID='<你的 client_id>'
export CLIENT_SECRET='<你的 client_secret>'

curl -sS "$API_BASE/v1/oauth/token" \
  -H 'Content-Type: application/json' \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}"

成功返回：

{
  "access_token": "<Token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token 有效期为 1 小时，过期后重新获取。后续请求统一携带 Authorization: Bearer <Token>。应用被禁用后，现有 Token 立即失效。请勿将密钥或 Token 放入网页前端或公开代码。

4. 提交视频任务

POST /v1/videos。每个新任务必须提供唯一的 Idempotency-Key；遇到网络超时重试时，保持原键和原参数。

export ACCESS_TOKEN='<上一步取得的 Token>'

curl -sS "$API_BASE/v1/videos" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: project-001-shot-001-attempt-001' \
  -d '{
    "model": "ltx-2.5-mlx-q8",
    "prompt": "夕阳下的街道，一位女孩缓缓走向镜头，暖色光线，镜头平稳后退，电影质感。",
    "seconds": 5,
    "size": "704x1280",
    "audio": true
  }'

成功返回 HTTP 202，关键字段如下：

{
  "id": "vid_<任务ID>",
  "status": "queued",
  "cost_fen": 60,
  "currency": "CNY",
  "billing_status": "frozen",
  "download_url": null
}

保存返回的 id，用于查询结果。提交成功代表任务已受理，视频稍后生成。

另支持测试尺寸 512x320。输出为 24fps MP4，实际文件时长可能略大于请求时长。生成需要排队，建议每 5 秒查询一次，离开页面不会取消任务。

提交前可用相同请求体调用 POST /v1/videos/quote，返回 {"cost_fen":60,"currency":"CNY"}，此操作不扣费、不生成。余额查询：GET /v1/balance。

5. 查询与下载

查询任务

export TASK_ID='<提交返回的 id>'
curl -sS "$API_BASE/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

完成时关键字段如下，示例时间为 Unix 秒：

{
  "id": "vid_<任务ID>",
  "status": "completed",
  "cost_fen": 60,
  "currency": "CNY",
  "billing_status": "charged",
  "download_url": "https://<临时下载地址>",
  "download_url_expires_at": 1792202400,
  "expires_at": 1792285200,
  "error": null
}

直接访问 download_url 下载 MP4，不要在下载请求中携带接口 Token。

curl --fail --location '<download_url 的完整值>' --output video.mp4

视频保留 1 天，请完成后立即下载到自己的存储。单条链接最多有效 1 小时，且不会超过视频保留截止时间。链接过期但视频仍在保留期内时，重新查询任务，或调用下述接口获取新链接，无需再次付费：

curl -sS "$API_BASE/v1/videos/$TASK_ID/download" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

查看最近任务：GET /v1/videos，返回 {"data":[...]}，默认最近 30 条，支持 ?limit_count=100（最多 100 条）。同一账户下的网站与应用可以查看该账户的任务；不同账户之间不可访问。

6. 图生视频

首帧支持 JPG / PNG / WebP，最大 20 MiB。流程如下：

1. 申请上传地址：POST /v1/images/uploads，携带 Token，JSON 请求体为 {"content_type":"image/jpeg"}。
2. 返回 id、upload_url、fields 和 expires_in:300。用 multipart/form-data POST，将返回的所有 fields 连同最后一个 file 字段上传到 upload_url；不要附加接口 Token。上传凭证有效 5 分钟，服务限制文件大小为 20 MiB。
3. 上传成功后调用 POST /v1/images/{id}/complete，携带 Token，提交空 JSON {}。
4. 按第 4 节提交生成任务，额外添加 "image_id":"<返回的 id>"。
5. 后续查询、下载与文生视频相同。

上传示例（Python，需安装 requests，upload 为第 1 步返回的 JSON）：

import requests

with open("first-frame.jpg", "rb") as image:
    response = requests.post(
        upload["upload_url"],
        data=upload["fields"],
        files={"file": ("first-frame.jpg", image, "image/jpeg")},
        timeout=120,
    )
response.raise_for_status()

请先充值再上传首帧。首帧也属于临时素材，请及时提交生成任务；隔天使用时重新上传。

7. 常见问题与错误

错误响应格式：

{
  "error": {
    "code": "insufficient_balance",
    "message": "可用余额不足，请先充值"
  }
}

提交超时怎么办？ 使用原幂等键、原参数重试。已拿到任务 ID 时继续查原任务，不要重复提交新任务。

生成失败怎么办？ 冻结费用会退回。修改描述或规格后，用新的幂等键重新生成。

Token 过期会影响生成吗？ 不影响后台任务。获取新 Token 后继续查询。

下载链接失效怎么办？ 在视频保留期内重新查询获取新链接；保留期结束后需要重新生成。

如何用网站生成？ 登录 → 充值到账 → 填写画面描述或上传首帧 → 选择模型、尺寸和时长 → 开始生成 → 在“我的作品”下载。无需创建应用或手动获取 Token。