把视频生成接入你的应用
Wan 3.0、Seedance 2.5 Flash 与 MiniMax H3,共用一套异步任务接口。
https://api.youqian666.vip/v1relax_mode 缺省为 true。显式 false 可关闭休闲,可能扣除平台积分。工作台仅向提交前积分大于 500 的合格账号派单,暂无合格账号时继续排队。Wan3 输出音频可用 audio 独立控制,默认开启。
鉴权
管理员在工作台创建 API Key,完整密钥仅创建时展示一次。所有 /v1 接口使用同一个请求头:
Authorization: Bearer pvk_替换为你的完整密钥密钥用于服务端调用。请通过环境变量读取,避免放进公开网页或代码仓库。
模型与能力
GET/v1/models对外 API 仅开放以下三个模型。管理员工作台中的其他模型不属于此 API 的开放范围。提交前可调用模型目录获取当前能力。
| 模型 ID | 时长 | 分辨率 | 默认分辨率 | 音频设置 |
|---|---|---|---|---|
wan-3.0Wan 3.0 | 2–30 秒 | 480p / 720p / 1080p | 720p | 默认 true,可关闭 |
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;多图参考使用前述六种固定比例,不支持auto。 - MiniMax H3:
21:9、16:9、4:3、1:1、3:4、9:16、auto;文字、单图首帧与多图参考相同。
时长必须为范围内整数。每次请求生成一个候选视频,不提供多候选数量参数。
多图参考上限:Wan 3.0 与 Seedance 2.5 Flash 最多 10 张,MiniMax H3 最多 9 张;至少 1 张。多图模式以模型目录的 referenceDurations、referenceQualities、referenceAspectRatios、referenceAudioSelectable 为准。
内部直连 URL 素材数量:Wan / Flash:最多 10 图、5 视频、5 音频,合计最多 20 份。H3:最多 9 图、3 视频、3 音频;参考音频必须同时配有参考图片或视频。
生成参数
| 字段 | 类型 / 必填 | 说明与默认值 |
|---|---|---|
model | 字符串 · 必填 | 上表中的精确模型 ID。 |
prompt | 字符串 · 必填 | 画面描述,1–5000 字符。 |
duration | 整数 · 可选 | 默认 5 秒;必须符合模型时长范围。 |
quality | 字符串 · 可选 | Wan / Flash 默认 720p;H3 默认 768p。 |
aspect_ratio | 字符串 · 可选 | 默认 16:9;Flash 单图生成默认且仅允许 auto。 |
audio | 布尔值 · 可选 | Wan 音频可选,省略默认仍为 true,显式 false 允许。Flash / H3 默认 false,不支持独立音频开关,请省略或设 false,声音由模型决定。 |
relax_mode | 布尔值 · 可选 | 默认 true。显式 false 关闭休闲,可能扣除平台积分。 |
reference_id | 字符串 · 可选 | 同一 API Key 上传得到的单图首帧 ID,兼容旧接口;与非空 reference_ids、media 互斥,不能填写 URL。 |
reference_ids | 字符串数组 · 可选 | 多图参考的有序唯一上传 ID 数组;1–N 张,上限 10 / 10 / 9;与非空 reference_id、media 互斥,不能填写 URL。 |
media | 对象数组 · 可选 | HTTPS 公网素材,元素为 {type,url};与非空上传 ID 字段互斥,first_frame 必须独占。 |
创建视频还必须携带 Idempotency-Key 请求头。同一次生成若因网络问题重发,请复用原值和相同参数。
上传参考图
POST/v1/files将 PNG、JPEG 或 WebP 文件作为原始二进制请求体发送,最大 10 MB。不是 multipart 表单,也不是 Base64 JSON。文件只可用于所属 API Key 的任务。
每个密钥最多100张图片、累计100MB,全服务上传上限1GB。并发上传每密钥最多2个、全服务最多4个。超限会拒绝,上传失败会清理本次素材。
平台确认受理并返回平台任务号后,本服务尽快删除上传图片和 URL 拉取素材的本地临时副本,不等待成片完成。本工作台的排队任务 ID 不等于平台受理回执。
多个任务共用同一素材时,尚待提交、正在提交但未取得回执,以及提交状态不明且缺少回执的任务继续保护文件。已取得平台受理回执和任务号的生成中任务,不再单独要求保留本地副本。
尚未被成功提交使用的上传文件,仍按创建满 24 小时后的规则回收。有受保护引用时暂不回收。只清理本服务保存的副本,不删除 URL 源站文件。
历史任务和幂等记录保留。旧任务仍可追踪,同幂等键与相同参数仍指向原任务。下次新任务需重新上传并使用新 ID,或重新提供有效源 URL 供服务拉取,不能复用已清理文件的 ID。
Authorization: Bearer ${PIXVERSE_API_KEY}
Content-Type: image/png
X-Filename: reference.png中文文件名先进行 URL 编码。上传结果中的 id 用作创建视频的 reference_id。
curl -X POST "https://api.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 或省略。
多图参考
先逐张调用 POST /v1/files,每张最多 10 MB,所有文件由同一 API Key 上传。再将返回的 ID 按预期顺序放入 reference_ids,不能重复;不使用多文件大请求。
reference_id 保留旧版单图首帧语义;reference_ids 使用多图参考流程,即使数组只有一张也不等同于单图首帧。reference_id、reference_ids、media 均不传时才为文字生成;三者非空时互斥。上传 ID 的旧含义不变。
{
"model": "wan-3.0",
"prompt": "按描述生成连续画面,保留参考图片中的视觉元素。",
"duration": 5,
"quality": "720p",
"aspect_ratio": "16:9",
"audio": true,
"relax_mode": true,
"reference_ids": ["file_第一张图片ID", "file_第二张图片ID"]
}示例 ID 需替换为上传结果。服务保留数组索引原样传递,不自动排序、删除图片、添加角色标签或推断模型引用语法。提示词中的引用方式由目标模型决定。
Flash 单图首帧只允许 auto;多图参考允许 21:9、16:9、4:3、1:1、3:4、9:16,不含 auto。工作台从 10 张切到 H3 时保留全部图片并阻止提交,需手动删到 9 张,不会静默截断。
多图参考尚未做真实生成验证,不承诺免费。历史单图样片也不能作为多图验收证据。
URL 参考素材
使用 POST /v1/videos 的 media 数组,每项填写 type 和 url。
| 类型 | 格式与单份上限 |
|---|---|
reference_image 或 first_frame | PNG、JPEG、WebP,10 MiB |
reference_audio | MP3、WAV,15 MiB |
reference_video | MP4、MOV,50 MiB |
首帧需要独占数组。URL 使用标准 443 端口的公网 HTTPS 链接,有效期覆盖排队和处理时间。每个任务最多 100 MiB,并遵守模型的数量限制。media 与 reference_id、reference_ids 互斥。
生成、查询与下载
/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 的任务。
成功查询默认提供 content_url。需要原始成片地址时,在查询中增加 ?include=video_url。只有存在且通过服务校验的原始 HTTPS 链接时,才会包含 video_url,否则可不出现该字段。
GET /v1/videos/{id}?include=video_url原始链接可能带签名并过期,请及时下载。不承诺重新查询自动续签。访问 video_url 不附带工作台 Key。查询任务与调用 content_url 仍需 Bearer 鉴权,原下载接口保留。
/v1/videos/{id}/content
下载视频仅在状态为 completed 后下载;下载请求也必须携带 Bearer 密钥。
curl -L "https://api.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 | 任务已取消 | 结束本次流程。 |
关闭休闲的任务不计入工作台的单账号休闲并发和每小时受理额度。API Key 限制与平台实际容量仍生效。
服务按调用方选择的休闲模式和音频设置提交。失败或结果不明时,服务不会自动重试、换号、换模型或切换休闲模式。
从首次确认平台排队起满 10 分钟且最新查询仍确认排队时,任务返回 failed,错误码为 PLATFORM_QUEUE_TIMEOUT。原任务与幂等键保留,账号名额在原平台任务结束后释放。
额度与幂等
本工作台 Key 的 dailyLimit: 0 表示每日受理任务数不限量。可设置为 0–10000 的整数。新建默认仍为 60,历史正值继续有效,可在密钥卡片保存调整。活跃任务、每分钟频率、账号执行上限和平台权益仍按各自设置独立判断。仍可能因其他限制收到 429。此设置只控制本工作台自己的受理日限。
maxActive: 0 表示单个 Key 已受理但尚未收尾的任务数不限量。新建默认仍为 2,正数可配置 1–20,可在密钥卡片保存。活跃任务包含排队、正在提交、生成中和结果不明。这不是平台账号的同时生成数量。账号调度、RPM、日额度和平台权益按各自设置独立生效,号池忙时任务继续排队。
一个生成意图对应一个幂等键
- 在
POST /v1/videos上提供Idempotency-Key,建议使用 UUID。发请求前保存该值。 - 同一密钥、同一幂等键、相同参数返回原任务,不新建任务,也不重复占用受理任务额度。
- 同一幂等键更换参数返回
409。一次新的生成应使用新的幂等键。 - 网络超时不能证明提交失败。先用相同幂等键和参数取得原任务;若任务为
requires_attention,由管理员核查,不另建任务绕过。
停用 API Key 不会取消已经受理的任务;停用后不能继续使用该密钥调用接口。
API Key 的 maxActive 限制受理后未收尾的任务,包含排队和结果不明。账号的 maxConcurrentTasks 控制同一真实账号的在途执行,由管理员配置,新账号默认 8、范围 1–20;重复账号槽不叠加,按平台权益校验。调高账号上限不会自动改变 Key 上限,池忙时排队属于正常行为。
向平台提交超时且未取得平台任务号时,任务返回 failed(CLI_TIMEOUT)并释放执行名额。已取得平台任务号后的状态查询超时会继续查询原任务。账号上限在工作台配置。
错误处理
{ "error": { "code": "错误代码", "message": "可读的错误原因" } }| HTTP 状态 | 处理方式 |
|---|---|
400 | 参数或请求头不正确;修正参数,不原样循环提交。 |
401 | 密钥缺失、错误或已停用;检查 Bearer 鉴权。 |
404 | 资源不存在,也可能不属于当前 API Key。 |
409 | 幂等键对应的参数发生变化,或当前资源状态不允许操作。 |
429 | 达到每日额度、活跃任务上限或请求频率限制;根据错误内容等待或联系管理员。 |
503 | 号池暂不可用;请联系管理员检查账号与服务状态。 |
错误原因以响应中的 error.code 和 error.message 为准;不要把生成失败当作必须自动重发的信号。
区分 HTTP 429 与任务详情中的限流
- 创建请求返回 HTTP 429 时,读取 Retry-After,保留原幂等键和参数,先核查任务是否受理。
- 已获得 202 和任务 ID:只轮询原任务。queued / in_progress 继续查询;查询本身返回 HTTP 429 时,按 Retry-After 等待后查询同一 ID。
- 详情即使以 HTTP 200 返回,也可能在错误字段中报告平台 429。按任务状态和错误内容区分;failed / requires_attention 不自动重发生成,由管理员核查。
普通查询建议间隔 10–20 秒,明确返回 Retry-After 时优先遵守。
完整代码示例
以下示例使用 Wan3、5 秒、720p,并显式开启休闲模式;cURL 示例显式关闭音频,Python / Node 示例开启音频,均可按需调整。多图接入见上节 reference_ids 示例。先在自己的终端设置环境变量;请保存本次的 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-21。服务实际返回的模型目录与错误信息优先。