P↗PixVerse 视频 API
v1下载 OpenAPI ↓管理工作台 ↗
API 接入文档

把视频生成接入你的应用

Wan 3.0、Seedance 2.5 Flash 与 MiniMax H3,共用一套异步任务接口。

接口地址https://pix.youqian666.vip/v1
1获取 API Key
→
2创建视频任务
→
3轮询任务进度
→
4下载完成视频
Wan3 强制使用休闲模式

relax_mode 缺省为 true,显式传 false 会被拒绝。其他模型也默认请求休闲模式;可用权益与实际消耗以平台返回为准,不承诺免费。

鉴权

管理员在工作台创建 API Key,完整密钥仅创建时展示一次。所有 /v1 接口使用同一个请求头:

Authorization: Bearer pvk_替换为你的完整密钥

密钥用于服务端调用。请通过环境变量读取,避免放进公开网页或代码仓库。

模型与能力

GET/v1/models

对外 API 仅开放以下三个模型。管理员工作台中的其他模型不属于此 API 的开放范围。提交前可调用模型目录获取当前能力。

模型 ID时长分辨率默认分辨率音频设置
wan-3.0Wan 3.02–30 秒480p / 720p / 1080p720p支持 true / false
seedance-2.5-flashSeedance 2.5 Flash4–30 秒480p / 720p720p声音由模型决定
minimax-h3MiniMax H35–15 秒768p / 1440p768p声音由模型决定

画幅

  • Wan 3.0:auto、16:9、4:3、1:1、3:4、9:16;文字与单图生成相同。
  • Seedance 2.5 Flash:文字生成支持 21:9、16:9、4:3、1:1、3:4、9:16;单图生成仅支持 auto。
  • MiniMax H3:21:9、16:9、4:3、1:1、3:4、9:16、auto;文字与单图生成相同。

时长必须为范围内整数。每次请求生成一个候选视频,不提供多候选数量参数。

生成参数

字段类型 / 必填说明与默认值
model字符串 · 必填上表中的精确模型 ID。
prompt字符串 · 必填画面描述,1–5000 字符。
duration整数 · 可选默认 5 秒;必须符合模型时长范围。
quality字符串 · 可选Wan / Flash 默认 720p;H3 默认 768p。
aspect_ratio字符串 · 可选默认 16:9;Flash 单图生成默认且仅允许 auto。
audio布尔值 · 可选默认 false。Wan 可设置 true;Flash / H3 不支持独立音频开关,请省略或设 false,声音由模型决定。
relax_mode布尔值 · 可选默认 true;Wan 显式 false 被拒绝,其他两个模型可传布尔值。权益与消耗由平台确认。
reference_id字符串 · 可选同一 API Key 上传得到的参考图文件 ID;不传为文字生成。

创建视频还必须携带 Idempotency-Key 请求头。同一次生成若因网络问题重发,请复用原值和相同参数。

上传参考图

POST/v1/files

将 PNG、JPEG 或 WebP 文件作为原始二进制请求体发送,最大 10 MB。不是 multipart 表单,也不是 Base64 JSON。文件只可用于所属 API Key 的任务。

每个密钥最多100张图片、累计100MB,全服务上传上限1GB。并发上传每密钥最多2个、全服务最多4个。超限会拒绝,上传失败会清理本次素材;文件不因完成生成自动删除。

请求头
Authorization: Bearer ${PIXVERSE_API_KEY}
Content-Type: image/png
X-Filename: reference.png

中文文件名先进行 URL 编码。上传结果中的 id 用作创建视频的 reference_id。

curl -X POST "https://pix.youqian666.vip/v1/files" \
  -H "Authorization: Bearer ${PIXVERSE_API_KEY}" \
  -H "Content-Type: image/png" \
  -H "X-Filename: reference.png" \
  --data-binary @reference.png
Flash 单图生成需要自动画幅

使用 seedance-2.5-flash 并提供 reference_id 时,aspect_ratio 设为 auto 或省略。

生成、查询与下载

POST

/v1/videos

创建异步任务
{
  "model": "wan-3.0",
  "prompt": "清晨海边,一位旅人沿着岸线缓慢前行,镜头平稳跟随。",
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "16:9",
  "audio": false,
  "relax_mode": true
}

受理后返回 HTTP 202。保存任务 id;响应中的 parameters 记录规范化后的请求参数。content_url 可在任务完成后出现。

{
  "id": "video_示例任务号",
  "object": "video",
  "status": "queued",
  "parameters": {
    "model": "wan-3.0",
    "duration": 5,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "relax_mode": true
  }
}

以上是字段说明用的示例响应,不是真实生成记录。

GET

/v1/videos/{id}

查询状态

建议间隔 10–20 秒轮询。仅能查询属于当前 API Key 的任务。

GET

/v1/videos/{id}/content

下载视频

仅在状态为 completed 后下载;下载请求也必须携带 Bearer 密钥。

curl -L "https://pix.youqian666.vip/v1/videos/${VIDEO_ID}/content" \
  -H "Authorization: Bearer ${PIXVERSE_API_KEY}" \
  --output video.mp4

任务状态

状态含义调用方动作
queued已受理,等待账号继续查询。
in_progress正在提交或生成继续查询,不创建重复任务。
completed视频已完成调用 content 接口下载。
failed生成失败读取错误原因,不自动重试。
requires_attention提交结果不明,需要核查停止自动操作,联系管理员核查平台记录。
cancelled任务已取消结束本次流程。

失败或结果不明时,服务不会自动重试、换号、换模型,也不会关闭 Wan3 的休闲模式。

额度与幂等

60默认每日受理任务数按北京时间自然日计算
2默认活跃任务上限包含排队、生成和结果不明
60默认每分钟请求数管理员可为各密钥分别设置

一个生成意图对应一个幂等键

  • 在 POST /v1/videos 上提供 Idempotency-Key,建议使用 UUID。发请求前保存该值。
  • 同一密钥、同一幂等键、相同参数返回原任务,不新建任务,也不重复占用受理任务额度。
  • 同一幂等键更换参数返回 409。一次新的生成应使用新的幂等键。
  • 网络超时不能证明提交失败。先用相同幂等键和参数取得原任务;若任务为 requires_attention,由管理员核查,不另建任务绕过。

停用 API Key 不会取消已经受理的任务;停用后不能继续使用该密钥调用接口。

错误处理

{ "error": { "code": "错误代码", "message": "可读的错误原因" } }
HTTP 状态处理方式
400参数或请求头不正确;修正参数,不原样循环提交。
401密钥缺失、错误或已停用;检查 Bearer 鉴权。
404资源不存在,也可能不属于当前 API Key。
409幂等键对应的参数发生变化,或当前资源状态不允许操作。
429达到每日额度、活跃任务上限或请求频率限制;根据错误内容等待或联系管理员。
503号池暂不可用;请联系管理员检查账号与服务状态。

错误原因以响应中的 error.code 和 error.message 为准;不要把生成失败当作必须自动重发的信号。

完整代码示例

以下示例使用 Wan3、5 秒、720p、休闲模式。先在自己的终端设置环境变量;请保存本次的 PIXVERSE_REQUEST_ID,同一次生成重发时保持不变。

export PIXVERSE_API_KEY='pvk_替换为你的完整密钥'
export PIXVERSE_REQUEST_ID='替换为本次唯一请求ID'

Python 需要安装 requests;Node.js 示例使用 Node 22+ 内置 fetch。示例不会因失败自动重新创建任务。

验证范围与实际消耗

目前只验证过一个 Wan3 真实生成任务

参数为 5 秒、480p,实测净扣 0。该结果只对应这一次任务;Seedance 2.5 Flash 和 MiniMax H3 尚未做真实生成验证,其他画质、时长、账号与权益的消耗不能由此推断。

休闲参数表示已请求该模式,不等于全部模型或账号均享有免费权益。平台明确拒绝时会保留原因,不自动切换到其他模式。

能力来源:PixVerse 官方 CLI 能力目录。当前文档整理日期:2026-11-20。服务实际返回的模型目录与错误信息优先。