拍我AI PixVerse视频生成 API 文档

概述

本文档介绍通过标准视频任务接口调用拍我 AI 视频生成能力的方法，支持文生视频、图生视频、视频延长、视频编辑、对口型、音效、超清等多种模式。

接口地址

POST /v1/video/generations

鉴权方式

在请求 Header 中携带 API Key：

支持的模型

模型名	说明
`PixVerse-V6`	旗舰生成模型，支持 1~15 秒任意时长，最高 1080P
`PixVerse-C1`	高质量创意模型，支持 1~15 秒任意时长，最高 1080P

请求参数

顶层字段

参数	类型	必填	说明
`model`	string	是	模型名称，见上表
`prompt`	string	是	视频内容的文字描述，越具体效果越好
`images`	array[string]	否	参考图片的公网 URL 列表。图生视频传 1 张，首尾帧传 2 张
`aspect_ratio`	string	文生视频建议传	画面比例，枚举见下方。仅文生视频（无参考图）时生效；图生视频输出比例由参考图决定，传了也会被忽略。文生视频不传时平台自动按 `16:9` 处理
`duration`	integer	是	生成时长（秒）。必填，不传报错。V6/C1 支持 1~15
`seed`	integer	否	随机种子，固定相同种子可复现结果
`metadata`	object	是	扩展参数，传入能力开关和清晰度等，详见下方

`aspect_ratio` 可选值

基础档（所有模型）：

值	说明
`16:9`	横屏（默认）
`9:16`	竖屏
`4:3`	标准
`3:4`	竖版标准
`1:1`	正方形

V6 / C1 额外支持：2:3 / 3:2 / 21:9

`metadata` 扩展字段

参数	类型	说明
`action`	string	能力模式，不传时自动判断（有图→ `img`，无图→ `text`）。枚举见下方
`quality`	string	必填。输出清晰度：`360p` / `540p` / `720p` / `1080p`。不传直接报 `[400017] Required field quality are missing or empty.`
`generate_audio_switch`	boolean	是否生成音频（适用于 V6 / C1），默认 `false`
`generate_multi_clip_switch`	boolean	是否开启多镜头（仅适用于 V6），默认 `false`
`sound_effect_switch`	boolean	是否生成音效（适用于 V5 及以下），默认 `false`
`sound_effect_content`	string	音效描述文本，需配合 `sound_effect_switch: true`
`lip_sync_switch`	boolean	是否开启对口型（适用于 V5 及以下），默认 `false`
`lip_sync_tts_content`	string	对口型 TTS 文本内容
`lip_sync_tts_speaker_id`	string	TTS 音色 ID
`template_id`	integer	特效模板 ID，使用视频模板时传入
`duration`	integer	生成时长（秒），优先级高于顶层 `duration`

`action` 枚举

值	说明
`text`	文生视频（无图时的默认行为）
`img`	图生视频（有图时的默认行为）。仅支持单张图，传多张报 `[400017] img_ids is not supported in this case.`
`transition`	首尾帧生成，`images` 传两张图作为起始和结束帧
`extend`	视频延长（需传视频引用，见下方「视频输入类玩法」）
`fusion`	多主体多参考图生视频，支持 1~7 张参考图，可用 `@ref_name` 在 prompt 中指代
`lip_sync`	对口型（需传视频引用 + 音频引用）
`sound_effect`	音效生成
`restyle`	视频重绘（需传视频引用 + `restyle_id`）
`swap`	主体替换
`multi_transition`	智能多帧
`mimic`	动作模仿
`modify`	视频编辑
`upscale`	超清视频
`avatar`	图片数字人
`agent`	爆款复刻 / 场景化智能生成

多图场景怎么选：
1 张图 → img（图生视频）
2 张图作首尾帧 → transition（第一张为起始帧，第二张为结束帧）
多张图作主体/背景参考（1~7 张） → fusion（多主体多参考图）
img 只接受单图，传多张会被上游拒绝。

视频输入类玩法（重要）

视频延长、视频重绘、视频编辑、超清、动作模仿、对口型、音效生成等玩法需要以已有视频作为输入，必须先获取视频引用 ID。

两个视频引用参数（二选一必填）

参数	类型	说明
`video_media_id`	integer	通过「上传资源」接口上传视频获得的 `media_id`
`source_video_id`	integer	本平台之前生成视频任务的 `video_id`（即提交响应的 `task_id`）

两者必须且只能传一个，同时传或都不传会报 [400017] Either "source_video_id" or "video_media_id" must be provided.

参数放置位置

视频引用参数放在 metadata 对象内，与 action、quality 同级：

{
  "model": "PixVerse-V6",
  "prompt": "镜头继续向前推进",
  "duration": 5,
  "metadata": {
    "action": "extend",
    "quality": "720p",
    "video_media_id": 429048494022506
  }
}

完整调用步骤（视频延长为例）

调用 POST /pixverse/openapi/v2/media/upload 上传源视频：

响应：{"ErrCode":0,"ErrMsg":"success","Resp":{"media_id":429048494022506,...}}

提交生成任务，把 media_id 填入 metadata.video_media_id：

{
  "model": "PixVerse-V6",
  "prompt": "The camera continues moving forward into the city",
  "duration": 5,
  "metadata": {
    "action": "extend",
    "quality": "720p",
    "video_media_id": 429048494022506
  }
}

轮询 GET /v1/video/generations/{task_id} 获取结果。

对口型（lip_sync）额外要求

对口型需要视频 + 音频两个引用，音频用 audio_media_id（同样是「上传资源」接口上传音频得到）：

{
  "model": "PixVerse-V6",
  "prompt": "lip sync",
  "duration": 3,
  "metadata": {
    "action": "lip_sync",
    "quality": "360p",
    "video_media_id": 429048494022506,
    "audio_media_id": 429048496816171
  }
}

音频参数与 TTS 二选一：也可以不传 audio_media_id，改用 lip_sync_tts_speaker_id + lip_sync_tts_content 由平台 TTS 生成语音。

素材限制

玩法	视频限制	音频限制
视频延长 / 音效 / 重绘	≤50MB，≤30 秒	≤50MB，≤30 秒
对口型	≤100MB，≤60 秒	≤100MB，≤60 秒
视频编辑 / 动作模仿 / 主体替换	≤100MB，≤30 秒	无需音频

视频分辨率最长边 ≤1920px，帧率 ≤120 FPS；主体替换要求编码为 H.264 / H.265。

请求示例

文生视频（带音频，720P，8 秒）

{
  "model": "PixVerse-V6",
  "prompt": "一只猫咪在阳光下慵懒地伸懒腰，镜头缓慢推进",
  "aspect_ratio": "16:9",
  "duration": 8,
  "metadata": {
    "quality": "720p",
    "generate_audio_switch": true
  }
}

图生视频（注意 duration 必填）

{
  "model": "PixVerse-C1",
  "prompt": "人物自然地走路，镜头慢慢跟随",
  "duration": 5,
  "images": ["https://example.com/portrait.jpg"],
  "metadata": {
    "quality": "720p"
  }
}

多镜头文生视频（V6 专属）

{
  "model": "PixVerse-V6",
  "prompt": "城市清晨，人们开始了一天的生活",
  "aspect_ratio": "16:9",
  "duration": 10,
  "metadata": {
    "quality": "720p",
    "generate_audio_switch": true,
    "generate_multi_clip_switch": true
  }
}

多主体多参考图（fusion）

支持 1~7 张参考图，用 ref_name 给每张图命名后，可在 prompt 中以 @名称 精确指代：

{
  "model": "PixVerse-V6",
  "prompt": "@dog 在 @room 里奔跑，电影感光线",
  "duration": 5,
  "aspect_ratio": "16:9",
  "images": [
    "https://example.com/dog.jpg",
    "https://example.com/room.jpg"
  ],
  "metadata": {
    "action": "fusion",
    "quality": "720p"
  }
}

如需为参考图命名，可直接在 metadata 中传入完整的 image_references（此时 images 可省略）：

{
  "model": "PixVerse-V6",
  "prompt": "@dog 在 @room 里奔跑，电影感光线",
  "duration": 5,
  "aspect_ratio": "16:9",
  "metadata": {
    "action": "fusion",
    "quality": "720p",
    "image_references": [
      { "img_id": 123456, "ref_name": "dog" },
      { "img_id": 123457, "ref_name": "room" }
    ]
  }
}

img_id 由「上传图片」接口获得。@ref_name 后需保留空格，名称须与 ref_name 完全一致。

使用特效模板

{
  "model": "PixVerse-V6",
  "prompt": "人物随音乐节奏舞动",
  "duration": 5,
  "images": ["https://example.com/photo.jpg"],
  "metadata": {
    "quality": "720p",
    "template_id": 100023
  }
}

提交响应

提交成功后返回任务信息，HTTP 状态码 200：

{
  "id": "4934015624718474",
  "task_id": "4934015624718474",
  "object": "video",
  "model": "PixVerse-V6",
  "status": "",
  "progress": 0,
  "created_at": 1792286416
}

字段	说明
`id` / `task_id`	任务唯一 ID，用于后续查询
`object`	固定为 `video`
`model`	本次使用的模型名
`status`	提交后为空串，以 HTTP 200 + `task_id` 非空作为受理成功的标准
`progress`	提交时固定为数字 `0`
`created_at`	任务创建时间（Unix 时间戳，秒）

任务查询

视频任务为异步执行，提交后通过以下接口轮询状态：

GET /v1/video/generations/{task_id}

⚠ 重要：终态判断看 data.status，不是顶层字段。
顶层 code 只表示「本次查询请求成功」，不代表视频已生成完成。

查询响应示例（生成完成）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "4934015624718474",
    "action": "text",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://media.example.com/xxx.mp4",
    "submit_time": 1792286415,
    "start_time": 1792286417,
    "finish_time": 1792286433,
    "progress": "100%",
    "data": {
      "Resp": { "...上游原始响应..." }
    }
  }
}

查询响应示例（生成中）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "4934015624718474",
    "action": "text",
    "status": "IN_PROGRESS",
    "fail_reason": "",
    "result_url": "",
    "submit_time": 1792286415,
    "start_time": 1792286417,
    "finish_time": 0,
    "progress": "50%"
  }
}

查询响应示例（生成失败）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "4934015624718474",
    "action": "text",
    "status": "FAILURE",
    "fail_reason": "moderation failed",
    "result_url": "",
    "submit_time": 1792286415,
    "progress": "100%"
  }
}

字段说明

字段	类型	说明
`code`	string	查询请求本身是否成功，`"success"` 表示查到了任务。不代表视频生成完成
`message`	string	查询层面的错误信息，正常为空串
`data.task_id`	string	任务 ID
`data.action`	string	本次任务的能力类型，如 `text` / `img` / `extend`
`data.status`	string	任务真实状态（大写），终态判断以此字段为准，取值见下表
`data.result_url`	string	视频下载地址，仅 `SUCCESS` 时非空。地址有时效，建议及时转存
`data.fail_reason`	string	失败原因，仅 `FAILURE` 时非空
`data.progress`	string	进度百分比字符串，如 `"50%"` / `"100%"`
`data.submit_time`	integer	提交时间（Unix 时间戳，秒）
`data.start_time`	integer	开始生成时间（Unix 秒），未开始为 `0`
`data.finish_time`	integer	完成时间（Unix 秒），未完成为 `0`
`data.data`	object	上游原始响应透传，一般无需解析

`data.status` 取值

值	含义	是否终态
`SUCCESS`	生成成功，取 `data.result_url`	✅ 是
`FAILURE`	生成失败，看 `data.fail_reason`	✅ 是
`IN_PROGRESS`	生成中	❌ 继续轮询
`QUEUED`	排队中	❌ 继续轮询

轮询代码示例

建议轮询策略

阶段	建议间隔
提交后前 30 秒	每 5 秒查询一次
30 秒后	每 10~15 秒查询一次
超过 10 分钟	视为超时，停止轮询

实测端到端时间：文生视频约 17~71 秒，图生视频通常更快。

图片参数说明

images 字段支持以下两种方式传入参考图：

公网 URL：直接传图片的 http/https 地址，系统自动上传换取 img_id（无感知）

img_id：先调用「上传图片」接口拿到 img_id，再将 img_id 作为字符串传入 images

图片要求：

格式：JPG / PNG / WEBP

大小：建议不超过 10MB

链接：公网可直接访问（不需要登录或 Cookie）

上传图片

如需提前上传图片并复用 img_id（例如多个视频共用同一张参考图），可以调用此接口。

接口地址

POST /pixverse/openapi/v2/image/upload

鉴权

请求参数（multipart/form-data）

参数	类型	必填	说明
`image`	file	与 `image_url` 二选一	图片文件，支持 JPG / PNG / WEBP，建议不超过 10MB
`image_url`	string	与 `image` 二选一	图片的公网 URL

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "img_id": 4929800001234567,
    "img_url": "https://media.example.com/images/xxx.jpg"
  }
}

字段	说明
`Resp.img_id`	图片 ID，可在生成接口的 `images` 字段中直接传入
`Resp.img_url`	图片在平台侧的访问地址

上传资源（视频/音频）

用于视频延长、视频重绘、对口型等能力，需提前上传视频或音频素材。

接口地址

POST /pixverse/openapi/v2/media/upload

鉴权

请求参数（multipart/form-data）

参数	类型	必填	说明
`file`	file	与 `file_url` 二选一	视频或音频文件
`file_url`	string	与 `file` 二选一	视频或音频的公网 URL
`media_type`	string	是	资源类型：`video` 或 `audio`

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "media_id": 429015841109831,
    "media_type": "video",
    "url": "https://media.example.com/openapi/2b396675-4124-4fd9-ab75-53331ac18369.mp4"
  }
}

字段	说明
`Resp.media_id`	资源 ID
`Resp.media_type`	资源类型，与请求的 `media_type` 一致
`Resp.url`	资源在平台侧的访问地址

获取特效模板列表

查询当前可用的特效模板，用于拿到 template_id 后在生成接口中使用。

接口地址

GET /pixverse/openapi/v2/video/effects/templates/list

Query 参数

参数	类型	必填	说明
`type`	integer	否	模板类型：`1` 视频模板，`2` 图片模板；不传返回全部
`page`	integer	否	页码，默认 1
`pageSize`	integer	否	每页数量，支持 10 / 20 / 50 / 100，默认 20

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "effect_items": [
      {
        "template_id": 402331965264704,
        "display_name": "观众席抓拍",
        "display_prompt": "生成电影感观众席反应镜头。",
        "thumbnail_video_url": "https://media.example.com/template/preview.mp4",
        "qualities": ["360p", "540p", "720p", "1080p"],
        "effect_type": "1",
        "effect_length": [8],
        "topic_requirements": "主体类型：人物\n建议主体数量：1-2",
        "type": 1,
        "create_at": "2026-06-11 14:43:28",
        "credit_consume": [
          { "consume_desc_key": "360p", "credit": "55" },
          { "consume_desc_key": "540p", "credit": "78" },
          { "consume_desc_key": "720p", "credit": "100" },
          { "consume_desc_key": "1080p", "credit": "190" }
        ]
      }
    ]
  }
}

字段	说明
`template_id`	模板 ID，在生成接口的 `metadata.template_id` 中传入
`display_name`	模板名称
`qualities`	该模板支持的清晰度档位
`effect_length`	支持的视频时长（秒）
`topic_requirements`	输入素材要求（主体类型、数量等）
`credit_consume`	各分辨率档位的点数消耗参考

获取视频重绘列表

查询可用的重绘风格，用于 restyle 能力。

接口地址

GET /pixverse/openapi/v2/video/restyle/list

无必填参数，直接请求即可。

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "total": 8,
    "data": [
      {
        "restyle_id": 337045047335104,
        "name": "乖巧羊毛毡",
        "thumbnail": "https://media.example.com/felted_2.png"
      }
    ]
  }
}

字段	说明
`Resp.total`	可用重绘风格总数
`Resp.data[].restyle_id`	重绘风格 ID，在 `restyle` 玩法的 `metadata.restyle_id` 中传入
`Resp.data[].name`	风格名称
`Resp.data[].thumbnail`	风格预览图

TTS 音色管理

用于对口型（lip_sync）能力的自定义音色管理。

获取音色列表

GET /pixverse/openapi/v2/video/tts_speaker

Query 参数

参数	类型	必填	说明
`page_num`	integer	否	页码，默认 1
`page_size`	integer	否	每页数量，仅支持 `10` / `20` / `50` / `100` 四个值，其他值报 `[400017] Invalid value for page_size.`。缺省为 20
`speaker_type`	string	否	`system`（系统音色）/ `custom`（自定义）/ `all`（全部），默认 `all`

创建自定义音色

POST /pixverse/openapi/v2/video/tts_speaker
Content-Type: application/json

请求体参数参考官方文档，创建成功后返回 speaker_id，在生成接口的 metadata.lip_sync_tts_speaker_id 中传入。

删除自定义音色

DELETE /pixverse/openapi/v2/video/tts_speaker/{speaker_id}

将 speaker_id 填入路径参数即可。

输出清晰度通过 metadata.quality 控制：

值	说明
`360p`	低清，消耗最少
`540p`	标清（默认）
`720p`	高清
`1080p`	全高清，需账户开通 1080P 权限，否则报错

音频生成说明：

V6 / C1：使用 generate_audio_switch: true 开启

V5 及以下：使用 sound_effect_switch: true 开启音效，lip_sync_switch: true 开启对口型

并发限制

平台和上游均有并发约束，高并发接入请提前了解：

限制来源	规则	错误响应
平台侧	账户余额低于 200 元时，同一令牌最多 1 个视频任务同时进行	`403 quota_warning_concurrency_limit`
上游侧	上游账户级并发上限约为 3 个任务	`400 pixverse_submit_failed [500044]`

余额充足时平台侧限制自动放开；上游并发限制取决于账户套餐，如需提升请联系客服。

错误说明

错误码 / 描述	原因	处理建议
`[400017] Required field duration are missing or empty`	图生视频未传 `duration`	补充 `duration` 参数（建议传 5）
`[400017] Invalid value for model.`	模型名称不正确	检查 `model` 字段是否为支持的模型名
`[400017] invalid param`	参数格式或组合不支持	检查 `action` 与其他参数的组合
`[500044] 已达到并发限制`	触发上游并发上限	稍后重试，或联系客服扩容
`invalid_action`	`action` 不在支持列表内	检查 `metadata.action` 枚举值
`get_task_request_failed`	请求体格式错误	检查 JSON 格式是否完整
`quota_not_enough`	账户余额不足	充值后重试
`quota_warning_concurrency_limit`	触发平台并发限制	余额充值至 200 元以上，或等待当前任务完成
`moderation failed`	内容审核未通过	修改 prompt 或替换图片
`generation failed`	生成失败	可重试，多次失败请联系技术支持

注意事项

图生视频 duration 必填：传入 images 参数时，duration 必须显式传入（推荐传 5），否则报 [400017] Required field duration are missing or empty。

图生视频不支持 aspect_ratio：图生视频输出比例由参考图本身决定，传入 aspect_ratio 会被忽略。

多镜头（multi_clip）：仅 V6 模型支持。C1 传 generate_multi_clip_switch 会被上游显式拒绝（报 400017），不是静默忽略。

视频地址有时效：data.result_url 为临时地址，请在任务完成后及时下载到自有存储。

提交响应 status 为空串：提交成功的判断标准是 HTTP 200 且 task_id 非空，而非 status 字段值。

Prompt 建议：描述越具体效果越好，建议包含场景、主体动作和镜头语言，如"特写人物表情，镜头缓慢拉远"。

拍我AI PixVerse视频生成 API 文档

概述#

支持的模型#

请求参数#

顶层字段#

aspect_ratio 可选值#

metadata 扩展字段#

action 枚举#

视频输入类玩法（重要）#

两个视频引用参数（二选一必填）#

参数放置位置#

完整调用步骤（视频延长为例）#

对口型（lip_sync）额外要求#

素材限制#

请求示例#

文生视频（带音频，720P，8 秒）#

图生视频（注意 duration 必填）#

多镜头文生视频（V6 专属）#

多主体多参考图（fusion）#

使用特效模板#

提交响应#

任务查询#

查询响应示例（生成完成）#

查询响应示例（生成中）#

查询响应示例（生成失败）#

字段说明#

data.status 取值#

轮询代码示例#

建议轮询策略#

图片参数说明#

上传图片#

上传资源（视频/音频）#

获取特效模板列表#

获取视频重绘列表#

TTS 音色管理#

获取音色列表#

创建自定义音色#

删除自定义音色#

并发限制#

错误说明#

注意事项#

概述

支持的模型

请求参数

顶层字段

`aspect_ratio` 可选值

`metadata` 扩展字段

`action` 枚举

视频输入类玩法（重要）

两个视频引用参数（二选一必填）

参数放置位置

完整调用步骤（视频延长为例）

对口型（lip_sync）额外要求

素材限制

请求示例

文生视频（带音频，720P，8 秒）

图生视频（注意 duration 必填）

多镜头文生视频（V6 专属）

多主体多参考图（fusion）

使用特效模板

提交响应

任务查询

查询响应示例（生成完成）

查询响应示例（生成中）

查询响应示例（生成失败）

字段说明

`data.status` 取值

轮询代码示例

建议轮询策略

图片参数说明

上传图片

上传资源（视频/音频）

获取特效模板列表

获取视频重绘列表

TTS 音色管理

获取音色列表

创建自定义音色

删除自定义音色

并发限制

错误说明

注意事项