把视频生成接入你的应用
Wan 3.0、Seedance 2.5 Flash 与 MiniMax H3,共用一套异步任务接口。
https://pix.youqian666.vip/v1relax_mode 缺省为 true,显式传 false 会被拒绝。其他模型也默认请求休闲模式;可用权益与实际消耗以平台返回为准,不承诺免费。
鉴权
管理员在工作台创建 API Key,完整密钥仅创建时展示一次。所有 /v1 接口使用同一个请求头:
Authorization: Bearer pvk_替换为你的完整密钥密钥用于服务端调用。请通过环境变量读取,避免放进公开网页或代码仓库。
模型与能力
GET/v1/models对外 API 仅开放以下三个模型。管理员工作台中的其他模型不属于此 API 的开放范围。提交前可调用模型目录获取当前能力。
| 模型 ID | 时长 | 分辨率 | 默认分辨率 | 音频设置 |
|---|---|---|---|---|
wan-3.0Wan 3.0 | 2–30 秒 | 480p / 720p / 1080p | 720p | 支持 true / false |
seedance-2.5-flashSeedance 2.5 Flash | 4–30 秒 | 480p / 720p | 720p | 声音由模型决定 |
minimax-h3MiniMax H3 | 5–15 秒 | 768p / 1440p | 768p | 声音由模型决定 |
画幅
- 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使用 seedance-2.5-flash 并提供 reference_id 时,aspect_ratio 设为 auto 或省略。
生成、查询与下载
/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
}
}以上是字段说明用的示例响应,不是真实生成记录。
/v1/videos/{id}
查询状态建议间隔 10–20 秒轮询。仅能查询属于当前 API Key 的任务。
/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 的休闲模式。
额度与幂等
一个生成意图对应一个幂等键
- 在
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。示例不会因失败自动重新创建任务。
验证范围与实际消耗
参数为 5 秒、480p,实测净扣 0。该结果只对应这一次任务;Seedance 2.5 Flash 和 MiniMax H3 尚未做真实生成验证,其他画质、时长、账号与权益的消耗不能由此推断。
休闲参数表示已请求该模式,不等于全部模型或账号均享有免费权益。平台明确拒绝时会保留原因,不自动切换到其他模式。
能力来源:PixVerse 官方 CLI 能力目录。当前文档整理日期:2026-11-20。服务实际返回的模型目录与错误信息优先。