PixVerse 视频生成

使用 EasyRouter 统一接口调用 PixVerse 全系列视频生成模型（C1 / V6 / V5.6 / V5.5 / V5 / V4.5 / V4 / V3.5），支持文生视频、图生视频。

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

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

一、支持的模型

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

模型	特点	时长档位	音频支持
`PixVerse/c1`	旗舰版，按秒计费最灵活	1~15 秒（按秒）	✓
`PixVerse/v6`	最新代，按秒计费	1~15 秒（按秒）	✓
`PixVerse/v5.6`	单片段模式，画质稳定	5 / 8 / 10 秒	✓
`PixVerse/v5.5`	支持 Multi-Clip 拼接	5 / 8 / 10 秒	✓
`PixVerse/v5`	第 5 代基础版	5 / 8 秒	✗
`PixVerse/v4.5`	第 4.5 代，支持 Fast Motion	5 / 8 秒	✗
`PixVerse/v4`	第 4 代，支持 Fast Motion	5 / 8 秒	✗
`PixVerse/v3.5`	第 3.5 代，支持 Fast Motion	5 / 8 秒	✗

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

二、通用接口

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

2.1 提交任务

POST /v1/videos

请求头

Header	必填	说明
`Authorization`	✓	`Bearer sk-你的APIKey`
`Content-Type`	✓	`application/json`

请求体字段

字段	类型	必填	说明
`model`	string	✓	PixVerse 模型名，见上表
`prompt`	string	✓	视频描述提示词，最长 2048 字符
`image`	string	—	图生视频模式的原图（URL 或 base64 data URI），传入后自动切换为图生视频
`images`	string[]	—	`image` 的数组形式（与 `image` 二选一）
`duration`	int	—	视频时长（秒），默认 5，不同模型支持的档位不同
`resolution`	string	—	分辨率档位（同 `size`，推荐使用，与其他模型对齐）：`720P` / `1080P`
`size`	string	—	分辨率，支持 `360p` `540p` `720p` `1080p`，或 `1920x1080` 这类像素格式。`resolution` 与 `size` 并存时 `resolution` 优先
`metadata`	object	—	PixVerse 特有参数容器（见第三节）

响应

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

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

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"
  }
}

状态枚举

状态	说明
`queued`	已提交，排队中
`in_progress`	生成中
`completed`	已完成，`metadata.url` 为视频地址
`failed`	生成失败，`error.message` 为失败原因

2.3 下载视频内容

GET /v1/videos/{task_id}/content

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

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

三、PixVerse 特有参数（metadata）

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

3.1 通用字段

字段	类型	适用模型	说明
`quality`	string	所有	分辨率，覆盖顶层 `size`，可选 `360p` `540p` `720p` `1080p`
`aspect_ratio`	string	文生视频	宽高比，如 `16:9` `9:16` `1:1` `4:3` `3:4` `2:3` `3:2` `21:9`
`motion_mode`	string	V4.5 / V4 / V3.5	运动模式，`normal`（默认）或 `fast`（×2 价格，仅 360p/540p/720p 的 5s 支持）
`camera_movement`	string	所有	镜头运动，如 `zoom_in` `zoom_out` `pan_left` `pan_right` 等
`seed`	int	所有	随机种子，0 ~ 2147483647
`template_id`	int	所有	模板 ID
`style`	string	所有	风格，如 `anime`
`water_mark`	bool	所有	是否添加水印
`negative_prompt`	string	所有	负面提示词

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）

字段	类型	适用模型	说明
`generate_audio_switch`	bool	C1 / V6 / V5.6 / V5.5	切换到"有音频"计费档位（由上游同步生成音频）

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

3.3 图生视频高级字段

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

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

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

字段	类型	说明
`img_id`	int	预上传的图片 ID，优先级高于 `image` 自动上传

四、完整调用示例

# Step 1: 提交任务
curl -X POST https://easyrouter.io/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://easyrouter.io/v1/videos/task_abc123... \
  -H "Authorization: Bearer sk-你的APIKey"

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

curl -X POST https://easyrouter.io/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://easyrouter.io/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://easyrouter.io/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 参数错误（提交前拦截，不扣费）

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

场景	错误信息
V5 / V4.5 / V4 / V3.5 传入 `generate_audio_switch: true`	`model "v5" does not support audio generation`
V4.5 / V4 / V3.5 的 `fast` 模式 + 1080p	`V4/V4.5/V3.5 fast motion only supports 360p/540p/720p at 5s`
V4.5 / V4 / V3.5 的 `fast` 模式 + 8s	同上
V5.6 / V5.5 / V5 不支持的 quality × duration 组合	`combination 1080p / 10s not supported`
未知模型名	`unknown model: "v999"`

5.2 HTTP 401 / 403 鉴权错误

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

5.3 HTTP 402 余额不足

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

5.4 任务 `failed` 状态

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

原因	说明	处理建议
`content moderation failed`	内容审核不通过	修改 prompt，避免敏感内容
`generation failed`	上游生成失败	重试，或降低分辨率/时长
`upstream timeout`	上游超时	稍后重试

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