XUMU API

文档

XUMU API 视频生成接口

pro 视频生成 API

01 / 概览

一套简单的异步视频接口

使用 XUMU API 时，你只需要创建任务，再查询任务结果。账号注册、余额和 API Key 可以在控制台完成管理。

02 / 接口

公开接口

视频接入只需要下面两个接口。Base URL 为 https://api.xumutv.com。

用途方法路径
创建视频任务POST/v1/videos/generations
查询视频任务GET/v1/videos/{task_id}

鉴权

在控制台创建 API Key 后，将它作为 Bearer 凭证放在请求头中。一个账号可以创建多把 Key，建议按环境或应用分别创建，撤销其中一把不会影响其他 Key。

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

控制台登录凭证仅用于管理账号；服务端调用请使用 API Key，不要把登录密码放进接口请求。

03 / 流程

异步任务流程

  1. 创建

    发送一次创建请求，成功后会得到任务 ID、排队状态和预估费用。

  2. 查询

    使用同一个任务 ID 调用查询接口。建议间隔至少 5 秒查询一次，直到任务进入终态。

  3. 读取结果

    状态为 succeeded 时读取完整的 video_url；失败时查看 error.code 和 error.message。

  4. 保存媒体

    媒体地址可能有有效期，请在业务服务端及时下载或转存。

终态包括 succeeded、failed、cancelled 和 expired。创建成功后请继续查询原任务，不要用重复创建代替查询。

创建任务

POST /v1/videos/generations

请求字段

字段 类型 必填 默认值 说明
model string 否 pro 公共模型名称，目前使用 pro。
prompt string 是 — 1–8000 个 Unicode 字符。
duration_seconds integer 否 4 4–15 秒；传 0 也使用 4 秒。
quality string 否 low low、standard、high、ultra。
aspect_ratio string 否 16:9 16:9、4:3、1:1、3:4、9:16、21:9。
audio_enabled boolean 否 true 是否生成同步音频。
include_watermark boolean 否 false 是否添加水印。
inputs array 否 [] 最多 12 个公网 HTTP(S) 参考素材。

inputs 的每一项使用 kind（image、video、audio）和 uri。视频素材必须额外提供 duration_seconds（2–600），所有视频素材时长合计不超过 3600 秒。

创建响应（HTTP 202）

{
  "id": "2e5b0b0b-2c77-4c84-a1f8-5b8e2e2d2c18",
  "object": "video.task",
  "model": "pro",
  "status": "queued",
  "estimated_cost": "1.840000",
  "currency": "CNY",
  "created_at": "2026-08-23T08:00:00Z"
}

Idempotency-Key 是可选请求头，不传也可以创建任务。如果你的服务会自动重试，建议为同一次业务请求生成一个唯一值；保持同一个值并使用相同请求内容重试，可以避免重复创建。

查询任务

GET /v1/videos/2e5b0b0b-2c77-4c84-a1f8-5b8e2e2d2c18

运行中响应：

{
  "id": "2e5b0b0b-2c77-4c84-a1f8-5b8e2e2d2c18",
  "object": "video.task",
  "model": "pro",
  "status": "processing",
  "video_url": null,
  "last_frame_url": null,
  "estimated_cost": "1.840000",
  "currency": "CNY",
  "created_at": "2026-08-23T08:00:00Z",
  "completed_at": null,
  "error": null
}

成功响应会把完整结果放在 video_url：

{
  "id": "2e5b0b0b-2c77-4c84-a1f8-5b8e2e2d2c18",
  "object": "video.task",
  "model": "pro",
  "status": "succeeded",
  "video_url": "https://api.xumutv.com/media/v1.eyJ2IjoxLCJ0IjoiLi4uIn0.example-signature",
  "last_frame_url": null,
  "estimated_cost": "1.840000",
  "billed_cost": "1.840000",
  "currency": "CNY",
  "created_at": "2026-08-23T08:00:00Z",
  "completed_at": "2026-08-23T08:04:00Z",
  "error": null
}

请使用完整的 video_url 播放或下载，不要截断协议、域名或路径。返回的是 XUMU API 域名下的短期签名地址，不会暴露底层存储位置；任务未进入对应状态时，video_url、billed_cost 和 completed_at 可能为 null 或不返回。

04 / 计费

预扣、结算与退款

创建任务时，系统会按质量、生成时长、参考视频时长和账号价格策略计算预估费用并锁定余额。任务成功后按实际用量结算；失败、取消或过期会释放预扣金额。

质量无视频参考含视频参考
low（480p）¥0.46 / 秒¥0.28 / 秒
standard（720p）¥1.00 / 秒¥0.61 / 秒
high（1080p）¥2.48 / 秒¥1.51 / 秒
ultra（4K）¥5.06 / 秒¥3.11 / 秒

例如，4 秒 low 文生视频的预估费用为 4 × 0.46 = ¥1.840000（未应用专属价格策略）。金额以 CNY 十进制字符串返回，避免浮点误差。

  • 画幅、音频和水印是生成参数，当前不额外改变价格。
  • 管理员可以为不同账号设置专属价格策略，实际费用以响应中的金额为准。
  • 余额不足会返回 HTTP 402，任务不会开始生成。

错误处理

所有错误都使用统一 envelope：

{
  "error": {
    "code": "insufficient_balance",
    "message": "余额不足，无法创建任务"
  }
}

常见状态码：

HTTP 含义 客户端建议
400 参数或 JSON 无效 修正请求后重试。
401 凭证无效或过期 检查 API Key 或在控制台重新创建。
402 余额不足 联系管理员充值。
403 凭证没有所需权限 使用有视频读写权限的 API Key。
404 任务不存在或不属于当前账号 确认 task ID。
409 请求内容与已有任务冲突 检查可选的幂等键和请求内容。
502/503 服务暂时不可用 退避后查询原任务，确认状态后再决定是否重试。

最小服务端示例

API_BASE_URL="https://api.xumutv.com"
API_KEY="你的用户 API Key"

curl -X POST "$API_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pro",
    "prompt": "雨夜城市街道，电影摄影，镜头缓慢向前推进",
    "duration_seconds": 4,
    "quality": "low",
    "aspect_ratio": "16:9",
    "audio_enabled": true,
    "include_watermark": false
  }'

curl "$API_BASE_URL/v1/videos/<TASK_ID>" \
  -H "Authorization: Bearer $API_KEY"