视频生成 API 文档

更新时间：2026-10-17。服务地址：https://103.42.182.232.nip.io:18443。 本文依据当前服务代码核对；示例中的 KEY、令牌、任务和代理 ID 均为占位符，不是真实凭据。

1. 鉴权与接口分类

三类凭据不能混用。客户无需提供上游账号 CK 或代理密码。不要把密钥写入公开页面、公开仓库、截图或日志。令牌失效返回 401；重新登录获取令牌。运行环境和入口网关可能有额外请求体限制。

2. 快速开始

以下为 Bash/curl 示例。设置 BASE 为服务根地址，不带 /v1/videos。

export BASE='https://103.42.182.232.nip.io:18443'
export VIDEO_API_KEY='YOUR_API_KEY'

curl --fail-with-body "$BASE/v1/client" \
  -H "Authorization: Bearer $VIDEO_API_KEY"

curl --fail-with-body "$BASE/v1/videos" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"秋风落叶","model":"video-2.0-fast","duration":5,"ratio":"16:9"}'

提交成功返回 202 和任务 id，不表示视频生成成功。保存该 ID，查询原任务，不要反复提交。

export TASK_ID='REPLACE_WITH_RETURNED_ID'
curl --fail-with-body "$BASE/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $VIDEO_API_KEY"

仅在 status=completed 后下载：

curl --fail-with-body -L "$BASE/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $VIDEO_API_KEY" -o video.mp4

下载可能返回 307 重定向到对象存储签名地址；不要使用 --location-trusted，不要把本站凭据转发到其他主机。也可以使用任务返回的 video_url；以 / 开头时需拼接服务根地址。

可运行 Python 示例：example.py.txt（以文本提供下载，运行时文件名使用 example.py）。安装依赖：python -m pip install requests。先设置 VIDEO_BASE_URL 和 VIDEO_API_KEY，运行 python example.py。该脚本会真实提交一条任务，可能产生费用。

3. 视频 API

提交参数

同时支持 JSON 和 multipart/form-data。推荐显式提供 model、duration、ratio。

图片默认最多30张、单张15 MiB；参考视频默认最多10个、音频默认最多10段，视频/音频单文件32 MiB。图片格式 JPEG/PNG/WebP，视频 MP4/MOV，音频 MP3/WAV。这些是本服务配置的接收上限，不是上游保证支持的数量或素材组合；内容、编码和模型仍可能被上游拒绝。生产配置和入口网关可能限制更严，过大的 multipart/base64 请求不建议一次发送。

URL 必须可由服务器访问；内网、回环和保留地址不允许。不要传只能在本机访问的路径。未提供独立的文件预上传接口：文件与生成请求一起上传，或使用已有公网对象 URL。

curl --fail-with-body "$BASE/v1/videos" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  -F 'prompt=秋风落叶' -F 'model=video-2.0-fast' -F 'duration=5' -F 'ratio=16:9' \
  -F 'image[]=@frame.jpg' -F 'video[]=@clip.mp4' -F 'audio[]=@track.mp3'

可重复 image[]、video[]、audio[] 字段提交多个文件。不要手写 multipart 的 Content-Type，客户端会自动生成 boundary。

响应与轮询

以下为字段结构示例，不是真实生成结果：

{
  "id": "video_EXAMPLE",
  "status": "queued",
  "model": "video-2.0-fast",
  "prompt": "秋风落叶",
  "video_url": null,
  "error": null,
  "progress": {
    "state": "queued",
    "position": 1,
    "ahead": 0,
    "running": 0,
    "workers": 0,
    "typical_seconds": 420,
    "eta_seconds": 0,
    "eta_text": "",
    "message": "等待符合条件的空闲账号",
    "blocker": {"code":"accounts_busy","message":"等待符合条件的空闲账号","retryable":true}
  }
}

建议每5–10秒查询一次，设定合理总等待时限。progress.message 是阶段说明，blocker 可能为 null；常见阻塞码包括 accounts_busy、client_concurrency、global_concurrency。ETA 仅为估算，不是承诺，workers=0 表示不设全局并发闸门，不代表没有服务器资源限制。HTTP 200、会话编号或心跳均不等于视频成功。

历史查询参数：limit 默认20，范围1–50；offset 默认0；status 可选上述状态。返回 total、limit、offset、tasks。只能读取当前 KEY 的任务，其他 KEY 的任务返回404。

HTTP 错误

错误通常返回 {"detail":"原因"}；框架字段校验也可能返回结构化数组，网关错误可能不是 JSON。

提交接口没有承诺幂等键。POST 超时/断线后不能认定“未受理”，先查任务列表或联系管理员核对；不要立即重复提交，避免重复计费。GET 查询失败可以退避重试。

4. 客户注册、登录与密钥

用户名格式与最小密码长度以 config 和校验返回为准。管理账号不能使用客户登录接口。密钥路径含敏感值，应避免记录完整 URL。

门户也可使用 POST /api/portal/generate 提交，以及 GET /api/portal/tasks、GET /api/portal/tasks/{id} 查询。使用 X-Portal-Key，不是 Bearer KEY；生成字段与上述一致，门户默认时长5秒，返回 {"ok":true,"quote":{},"task":{}} 结构，不是视频 API 的直接 TaskResponse。服务端集成优先使用 /v1/videos。

5. 管理员：静态 IP 按数量分配

管理员接口不是客户 KEY 权限。先登录取得 token：

curl --fail-with-body "$BASE/api/admin/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"YOUR_ADMIN_USERNAME","password":"YOUR_ADMIN_PASSWORD"}'

使用 X-Admin-Key: RETURNED_TOKEN 查询 GET /api/admin/accounts 和 GET /api/admin/proxies。使用返回的代理 id，不是 IP 地址作为 proxy_id。只允许选择已启用且 mode=static 的代理。

预览与应用

每条静态 IP 可保存自己的账号绑定上限。在管理面板的「代理管理 → 绑定数量」中设置，或调用：

PATCH /api/admin/proxies/PROXY_A_ID
X-Admin-Key: RETURNED_TOKEN
Content-Type: application/json

{"account_limit":20}

account_limit 是0-1000000的整数，0表示不限制；创建静态代理时也可传入。比如代理A设20、代理B设80，分别独立保存，服务重启后保留。保存上限本身不分配或解绑账号；要实际分配，使用下面的批量接口。

代理列表返回 account_count（已绑定数）、account_limit（上限）、account_slots（剩余名额；不限时为null）和 account_over_limit（已有绑定是否超限）。单号绑定、批量绑定及底层写入均检查静态代理容量；待应用绑定也预占名额。降低上限不会删除已有绑定，已绑账号可保留，但满额后不能新增。未设置过上限的旧代理默认为0，不改动旧绑定。

同批调整不会预先扣除即将迁出的账号，避免尚未生效的迁出让名额超卖。满额代理之间调换时，请先释放名额或临时调高上限。平均分配仍是均分本批账号，并非按容量加权，超限会明确报错。

POST /api/admin/accounts/allocate-static-proxies

指定数量示例：

{
  "names": ["acc1", "acc2", "acc3", "acc4", "acc5"],
  "mode": "custom",
  "allocations": [
    {"proxy_id": "PROXY_A_ID", "count": 1},
    {"proxy_id": "PROXY_B_ID", "count": 4}
  ],
  "preview": true
}

100个账号按20/80分配时，提交完整100个账号名，两个 count 分别填20和80。count 是本批分配数，account_limit 是该代理保存的总绑定上限。未在 names 中的账号不会更改或自动解绑；预览和应用时均会计入已有及待应用绑定，超过保存的上限会拒绝。

平均分配：mode=equal，allocations 只填各个 proxy_id 即可。100个号/2条代理为50/50；5个号/2条为3/2，余数按代理列表顺序分配。账号按 names 顺序分段，每个账号恰好分给一条代理，不会重复分配。

响应结构：

{
  "ok": true,
  "preview": true,
  "mode": "custom",
  "total": 5,
  "plan": [
    {"proxy_id":"PROXY_A_ID","proxy_name":"代理A","count":1,"names":["acc1"]},
    {"proxy_id":"PROXY_B_ID","proxy_name":"代理B","count":4,"names":["acc2","acc3","acc4","acc5"]}
  ],
  "updated": [],
  "queued": [],
  "failed": []
}

核对预览后，使用同一请求将 preview 改为 false 应用。接口重新校验账号和代理。updated 是立即生效账号；queued 是正在运行、等空闲后应用的账号；failed 是逐账号运行期失败列表。参数校验失败不写任何绑定；运行期失败允许部分成功，必须检查 failed，不能只看 HTTP 200。

分配不修改账号国家、调度开关、额度、限流状态，也不触发登录、探测或生成。静态代理配置不保证供应商实际公网出口固定、国家正确或账号不被限制。忙碌账号的待应用设置沿用现有内存队列，服务重启前未应用的设置不保证保留。应用前应保存原绑定快照，后续可用现有单号/批量代理接口恢复。

账号列表会返回待应用状态，可刷新检查；不要把“已提交待应用”误认为代理已经切换。