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

把视频生成接入你的应用

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

接口地址https://api.youqian666.vip/v1
1获取 API Key
→
2创建视频任务
→
3轮询任务进度
→
4下载完成视频
休闲模式默认开启

relax_mode 缺省为 true。显式 false 可关闭休闲,可能扣除平台积分。工作台仅向提交前积分大于 500 的合格账号派单,暂无合格账号时继续排队。Wan3 输出音频可用 audio 独立控制,默认开启。

鉴权

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

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

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

模型与能力

GET/v1/models

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

模型 ID时长分辨率默认分辨率音频设置
wan-3.0Wan 3.02–30 秒480p / 720p / 1080p720p默认 true,可关闭
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;多图参考使用前述六种固定比例,不支持 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
Flash 单图生成需要自动画幅

使用 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 多图参考使用固定画幅

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_framePNG、JPEG、WebP,10 MiB
reference_audioMP3、WAV,15 MiB
reference_videoMP4、MOV,50 MiB

首帧需要独占数组。URL 使用标准 443 端口的公网 HTTPS 链接,有效期覆盖排队和处理时间。每个任务最多 100 MiB,并遵守模型的数量限制。media 与 reference_id、reference_ids 互斥。

生成、查询与下载

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 的任务。

成功查询默认提供 content_url。需要原始成片地址时,在查询中增加 ?include=video_url。只有存在且通过服务校验的原始 HTTPS 链接时,才会包含 video_url,否则可不出现该字段。

GET /v1/videos/{id}?include=video_url

原始链接可能带签名并过期,请及时下载。不承诺重新查询自动续签。访问 video_url 不附带工作台 Key。查询任务与调用 content_url 仍需 Bearer 鉴权,原下载接口保留。

GET

/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。原任务与幂等键保留,账号名额在原平台任务结束后释放。

额度与幂等

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

本工作台 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 不会取消已经受理的任务;停用后不能继续使用该密钥调用接口。

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。示例不会因失败自动重新创建任务。

验证范围与实际消耗

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

参数为 5 秒、480p,实测净扣 0。该记录只覆盖当次参数,不能据此推断其他音频选择、多图模式或参数已通过验收;本轮未追加真实生成复测。该消耗结果只对应这一次任务;Seedance 2.5 Flash 和 MiniMax H3 尚未做真实生成验证,其他画质、时长、账号与权益的消耗不能由此推断。

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

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