快速开始

API 调用流程

接入PixVerse AI API仅需以下步骤：

创建 API Key

发起视频生成任务

获取 video_id

查询任务状态

获取视频下载地址

下载最终视频

前置条件

PixVerse AI开放平台账号

API Key

步骤1：创建 API Key

登录开放平台：https://platform.pai.video

在 API Key 页面点击 Create Key 创建新的 API Key。

一：创建您的 API Key在 “API Key” 区域，点击 Create key 按钮

二：请为您的 API 密钥输入名称

三：确认名称后，平台将显示您的 API 密钥；请妥善保存，因为该Key只会显示一次

请妥善保存您的 API Key。出于安全考虑，系统仅在创建时展示一次完整密钥。

步骤2：配置请求 Header

Header	说明
API-KEY	开放平台密钥创建的 API Key
Ai-trace-id	每次请求唯一的 UUID

示例：

关于 Ai-trace-id

Ai-trace-id 用于链路追踪，不是幂等键。

每次生成请求使用新的 UUID

不要重复使用历史请求的 Ai-trace-id

推荐使用标准 UUID v4

重复使用相同 Ai-trace-id 仍可能创建新的生成任务。请勿依赖该字段去重；重试前先确认原请求是否已返回任务 ID，避免重复提交。

步骤3：创建视频生成任务

素材准备

素材类型	需要先阅读的 API 文档	适用场景
图片素材	上传图片（API > 上传图片）	图生视频、视频模板、首尾帧、多主体、多帧过渡
图片 + 音频 + 视频素材	上传资源（视频/音频）（API > 上传资源(视频/音频)	视频延长、对口型、音效生成、视频重绘、主体替换、视频编辑、动作模仿、超清视频

选择对应的视频生成能力并发起请求。

功能	接口文档
文生视频	Text-to-Video
图生视频	Image-to-Video
特效视频	Video Effects

创建任务示例

响应结果

请保存返回的 video_id，后续查询任务状态需要使用该参数。

步骤4：查询任务状态

提交任务后，使用 video_id 查询视频生成状态。

实际响应使用统一的 ErrCode、ErrMsg、Resp 外层结构。任务 ID 位于 Resp.id，不是 Resp.video_id。

已完成示例：

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "id": 123456789,
    "prompt": "continue naturally",
    "negative_prompt": "",
    "resolution_ratio": 0,
    "url": "https://media.pixverseai.cn/path/to/video.mp4",
    "size": 34,
    "seed": 1424686686,
    "status": 1,
    "style": "",
    "create_time": "2026-07-26T12:17:09Z",
    "modify_time": "2026-07-26T12:18:04Z",
    "outputWidth": 960,
    "outputHeight": 540,
    "quality": "540p",
    "aspect_ratio": "",
    "has_audio": true,
    "credits": 75,
    "customer_paths": null
  }
}

处理中时，响应仍使用相同外层结构，判断依据为 Resp.status = 5。此时不要把 url 当作可用成品地址；继续轮询，直到状态进入成功或失败终态。

状态码说明

1：生成成功

5：处理中

7：内容审核未通过

8：生成失败

建议轮询间隔：当状态为 5（处理中）时，建议每 3–5 秒查询一次。

常见接入场景

文生视频（Text-to-Video）通过文本描述直接生成视频内容。

请求示例

响应示例

图生视频（Image-to-Video）通过上传图片作为参考素材生成视频。

Step1：上传图片

Step2：创建图生视频任务

Step3：查看成功响应

下一步

保存返回的 video_id，随后调用「查询视频状态」接口获取生成结果。

特效视频（Video Templates）通过指定模板 ID 快速生成热门特效视频。

调用流程：
上传图片
↓
获取 img_id
↓
选择 template_id
↓
创建视频任务
↓
获取 video_id

请求示例

响应示例

API 调用流程#

前置条件#

步骤1：创建 API Key#

步骤2：配置请求 Header#

关于 Ai-trace-id#

步骤3：创建视频生成任务#

步骤4：查询任务状态#

常见接入场景#

文生视频（Text-to-Video）通过文本描述直接生成视频内容。#

图生视频（Image-to-Video）通过上传图片作为参考素材生成视频。#

特效视频（Video Templates）通过指定模板 ID 快速生成热门特效视频。#