PixVerse 视频生成

PixVerse 是一家提供高质量 AI 视频生成服务的平台。AutoRouter 接入 PixVerse OpenAPI v2，通过 OpenAI 兼容的 /v1/videos 接口对外提供服务，覆盖 PixVerse 全部 8 个模型版本的文生视频与图生视频能力。

PixVerse 是异步任务型接口：提交后立即返回 task_id，你需要轮询任务状态，成功后通过代理接口下载视频。

一、支持的模型

调用时在 model 字段统一使用 PixVerse/<版本号> 的形式，例如 PixVerse/v5.6。

模型名中 PixVerse/ 前缀大小写敏感，建议严格使用 PixVerse/v5.6 这种格式。版本号部分（v5.6、c1）支持大小写自动 normalize。

二、通用接口

所有 PixVerse 模型、所有任务类型都通过 OpenAI 兼容的 /v1/videos 接口调用。

2.1 提交任务

POST /v1/videos

请求头

请求体字段

响应

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "PixVerse/v5.6",
  "status": "queued",
  "progress": 0,
  "created_at": 1730000000
}

id / task_id 是 AutoRouter 生成的公开 ID（task_ 前缀），用于后续查询。它不等于 PixVerse 上游的 video_id，请务必使用 AutoRouter 返回的这个值。

2.2 查询任务状态

GET /v1/videos/{task_id}

响应（进行中）

{
  "id": "task_xxxxxxxxxxxxx",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1730000000
}

响应（成功）

{
  "id": "task_xxxxxxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "created_at": 1730000000,
  "completed_at": 1730000060,
  "size": "1280x720",
  "metadata": {
    "url": "https://media.pixverse.ai/xxx.mp4"
  }
}

状态枚举

2.3 下载视频内容

GET /v1/videos/{task_id}/content

直接返回视频二进制流（Content-Type: video/mp4）。AutoRouter 会自动代理 PixVerse 的临时 URL，避免向客户端暴露上游地址，也避免临时 URL 过期问题。

强烈推荐使用 /content 代理接口下载视频，而不是直接访问 metadata.url。后者是 PixVerse 的临时链接，有效期有限（通常数小时）；而代理接口只要任务记录未清理就永不过期。

三、PixVerse 特有参数（metadata）

所有 PixVerse 特有字段都通过请求体的 metadata 对象传递。

3.1 通用字段

motion_mode: fast 有严格限制：仅 V4.5 / V4 / V3.5 模型、5 秒时长、360p/540p/720p 分辨率支持。传入其他组合（如 1080p + fast 或 8s + fast）会直接返回 400 错误，不会产生扣费。

3.2 视频音频生成（C1 / V6 / V5.6 / V5.5）

V5 / V4.5 / V4 / V3.5 不支持音频生成。这几个模型传入 generate_audio_switch: true 会返回 400 错误。

3.3 图生视频高级字段

PixVerse 图生视频要求先把图片上传到上游获取 img_id。AutoRouter 已自动封装了上传流程：

• 你直接在请求体传 image: "https://..." 或 image: "data:image/png;base64,..."
• AutoRouter 自动上传到 PixVerse，取回 img_id 后转发给视频生成接口

如果你已经有 img_id（高级场景），可以直接传：

四、完整调用示例

# Step 1: 提交任务
curl -X POST https://autorouter.top/v1/videos \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/v5.6",
    "prompt": "一只猫在月球表面漫步，背景是璀璨的星空",
    "duration": 5,
    "size": "720p",
    "metadata": {
      "aspect_ratio": "16:9",
      "seed": 42
    }
  }'

# 响应:
# {
#   "id": "task_abc123...",
#   "task_id": "task_abc123...",
#   "status": "queued",
#   ...
# }

# Step 2: 轮询任务状态（建议间隔 3~5 秒）
curl https://autorouter.top/v1/videos/task_abc123... \
  -H "Authorization: Bearer sk-你的APIKey"

# Step 3: 状态变为 completed 后，下载视频
curl https://autorouter.top/v1/videos/task_abc123.../content \
  -H "Authorization: Bearer sk-你的APIKey" \
  -o cat_on_moon.mp4

curl -X POST https://autorouter.top/v1/videos \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/v5.6",
    "prompt": "让这只猫跳起来",
    "image": "https://example.com/cat.jpg",
    "duration": 5,
    "size": "720p"
  }'

# 先把图片编码成 data URI
IMG_BASE64=$(base64 -i cat.jpg)

curl -X POST https://autorouter.top/v1/videos \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"PixVerse/v5.6\",
    \"prompt\": \"让这只猫跳起来\",
    \"image\": \"data:image/jpeg;base64,${IMG_BASE64}\",
    \"duration\": 5,
    \"size\": \"720p\"
  }"

# C1 / 720p / 5s / 同步生成音频
curl -X POST https://autorouter.top/v1/videos \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/c1",
    "prompt": "海浪拍打海岸，海鸥在天空盘旋",
    "duration": 5,
    "size": "720p",
    "metadata": {
      "generate_audio_switch": true,
      "aspect_ratio": "16:9"
    }
  }'

五、错误处理

5.1 HTTP 400 参数错误（提交前拦截，不扣费）

AutoRouter 在提交到上游前会严格校验参数组合。以下非法组合会返回 400 Bad Request：

5.2 HTTP 401 / 403 鉴权错误

• 401 Unauthorized: API Key 无效或已过期
• 403 Forbidden: API Key 无权访问此模型（检查 token 的模型白名单）

5.3 HTTP 402 余额不足

返回 insufficient user quota 错误。请前往 AutoRouter 控制台充值。

5.4 任务 failed 状态

任务提交成功但生成失败。常见原因：

任务 failed 时 AutoRouter 会自动退款到你的账户，你可以在日志页面查询退款记录。

六、常见问题

PixVerse 的 model 字段应该怎么填？

使用 PixVerse/<版本号> 的形式，例如：PixVerse/c1 / PixVerse/v6 / PixVerse/v5.6 / PixVerse/v5.5 / PixVerse/v5 / PixVerse/v4.5 / PixVerse/v4 / PixVerse/v3.5。PixVerse/ 前缀是对外展示名，调用时必须携带；版本号部分大小写不敏感，但建议使用小写。

size 填 '720p' 还是 '1280x720'？

两种都支持。AutoRouter 内部会统一映射到 PixVerse 的 quality 参数（360p / 540p / 720p / 1080p）。也支持 metadata.quality 覆盖顶层 size。

各模型支持的时长有什么不同？

• PixVerse/c1 / PixVerse/v6：按秒计费，1~15 秒任意
• PixVerse/v5.6 / PixVerse/v5.5：5 / 8 / 10 秒固定档位
• PixVerse/v5：5 / 8 秒固定档位
• PixVerse/v4.5 / PixVerse/v4 / PixVerse/v3.5：5 / 8 秒固定档位（fast 模式仅 5s）

填入不支持的时长会返回 400 错误，不会扣费。

图生视频必须先上传图片吗？

不需要。PixVerse 官方需要两步（上传 → 生成），但 AutoRouter 已封装成一步：你直接传 image: "https://..." 或 base64，后台自动上传并转发 img_id。如果你已有 img_id，可以在 metadata.img_id 传递以跳过上传。

任务通常多久能完成？

典型耗时参考：

• 360p / 540p / 5 秒视频：10 ~ 30 秒
• 720p / 5 秒视频：30 ~ 60 秒
• 1080p / 8 秒视频：60 ~ 120 秒
• 高并发时可能更久

建议轮询间隔 3~5 秒，最长等待不超过 10 分钟。

视频 URL 会过期吗？

PixVerse 返回的原始 metadata.url 是临时链接，有效期有限（通常数小时）。建议获取后尽快下载或转存到你自己的存储。

如何选择合适的模型？

• 追求最佳画质、按秒灵活计费：PixVerse/c1（旗舰版）
• 需要音频：PixVerse/c1 / PixVerse/v6 / PixVerse/v5.6 / PixVerse/v5.5
• 需要快速动作：PixVerse/v4.5 / PixVerse/v4 / PixVerse/v3.5 + motion_mode: fast
• 通用场景 / 性价比：PixVerse/v5.6（推荐默认）