视频重绘 Restyle

将已有视频转换为新的视觉风格，例如动漫、3D、电影感或增强写实风格。可以使用平台预设效果，也可以通过提示词自定义目标风格。

接口定位：视频生成任务接口。创建成功后返回 video_id，需要继续查询任务状态或等待 Webhook 回调才能取得最终视频。

接入流程

使用预设效果

准备源视频 -> 获取视频重绘列表 -> 选择 restyle_id -> 创建重绘任务 -> 查询状态或等待 Webhook

使用自定义提示词

准备源视频 -> 编写 restyle_prompt -> 创建重绘任务 -> 查询状态或等待 Webhook

请求 Header

Header	类型	是否必填	说明
`API-KEY`	string	是	PixVerse API Key。必须放在 Header 中。
`Ai-trace-id`	string	是	请求追踪 ID。每次创建任务建议使用新的 UUID。
`Content-Type`	string	是	固定为 `application/json`。

请求参数

参数	类型	是否必填	说明
`source_video_id`	integer	条件必填	PixVerse 已生成视频的 ID。与 `video_media_id` 必须且只能填写一个。
`video_media_id`	integer	条件必填	上传视频接口返回的 `media_id`。与 `source_video_id` 必须且只能填写一个。
`restyle_id`	integer	条件必填	预设效果 ID。与 `restyle_prompt` 必须且只能填写一个。
`restyle_prompt`	string	条件必填	自定义风格描述。与 `restyle_id` 必须且只能填写一个。
`seed`	integer	否	可选随机种子；省略时由服务端选择。
`webhook_id`	string	否	Webhook 配置 ID。填写后可通过回调接收任务结果。

参数组合规则

使用方式	视频来源	风格来源
PixVerse 视频 + 预设效果	`source_video_id`	`restyle_id`
上传视频 + 预设效果	`video_media_id`	`restyle_id`
PixVerse 视频 + 自定义风格	`source_video_id`	`restyle_prompt`
上传视频 + 自定义风格	`video_media_id`	`restyle_prompt`

校验规则：

source_video_id 与 video_media_id 必须且只能填写一个。

restyle_id 与 restyle_prompt 必须且只能填写一个。

两组字段同时填写、同组字段全部缺失时，应返回参数错误。

restyle_id 必须来自 GET /openapi/v2/video/restyle/list 的真实响应。

上传视频与素材限制

使用上传视频时，先调用：

上传成功后，将响应中的视频 media_id 填入 video_media_id。

根据当前重绘专属使用指南：

项目	限制
视频格式	`mp4`、`mov`
最大文件大小	`50MB`
最大分辨率	最长边不超过 `1920px`
时长	`1-16s`

最小请求示例：预设效果

{
  "source_video_id": 123456789,
  "restyle_id": 123
}

restyle_id: 123 仅用于展示字段位置，请替换为列表接口实际返回的效果 ID。

最小请求示例：自定义风格

{
  "video_media_id": 987654321,
  "restyle_prompt": "Turn the video into a warm anime style while preserving the original motion and composition."
}

完整 cURL 示例：PixVerse 视频 + 预设效果

完整 cURL 示例：上传视频 + 自定义风格

响应字段

字段	类型	说明
`ErrCode`	integer	业务错误码，`0` 表示成功。
`ErrMsg`	string	错误信息；成功时通常为 `Success`。
`Resp.video_id`	integer	视频任务 ID，用于查询生成状态。
`Resp.credits`	integer	创建响应返回的任务积分计算值，用于展示和对账；不应单独视为账户最终扣费凭证。

成功响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456789,
    "credits": 60
  }
}

HTTP 状态码为 200 只表示请求已到达服务端，仍需检查 ErrCode 是否为 0。

积分与计费

Restyle 按源视频时长计费，当前规则为 10 Credits/秒。示例中的 Resp.credits 只展示字段结构，不代表固定价格。最终扣费和失败返还以 Billing 用量明细、余额账本和任务最终状态为准。

常见错误

错误码 / 情况	说明	处理建议
`400013`	参数类型或值错误	检查 ID 类型、JSON 格式和可选字段。
`400017`	参数无效	检查两组互斥参数是否各选择一个。
`500044`	达到并发生成限制	等待已有任务完成后重试。
API Key 无效或缺失	鉴权失败	检查 `API-KEY` Header。
余额不足	无法创建任务	检查账号剩余点数。

查询任务状态

创建成功后，使用 Resp.video_id 调用：

`status`	状态说明	处理建议
`1`	生成完成	读取响应中的最终视频 `url`。
`5`	生成中	继续查询，或等待 Webhook 回调。
`7`	内容审核失败	调整提示词或替换输入视频后重新创建任务。
`8`	生成失败	根据错误信息处理，并保留 `Ai-trace-id` 排查。

Webhook 回调

视频重绘支持 Webhook。创建任务时传入 webhook_id 后，平台会向已配置地址推送任务状态。

回调接收端应验证 Webhook-Signature。

建议校验 Webhook-Timestamp，防止重放攻击。

成功接收后返回 HTTP 200，Body 为小写 ok。

回调可能重试，应使用任务 id 做幂等去重。

注意事项

不要同时填写 source_video_id 和 video_media_id。

不要同时填写 restyle_id 和 restyle_prompt。

使用预设效果前，先获取当前有效的重绘效果 ID。

自定义提示词建议聚焦视觉风格；需要保留原始动作、人物身份或构图时，应明确说明。

每次创建任务使用新的 Ai-trace-id。

API Key 属于敏感凭证，不要写入前端代码、公开日志或 URL。

视频重绘 Restyle