Pixverse 视频生成 API 对接说明
内容提要
本文介绍Pixverse视频生成API的对接方法。用户需在Ace Data Cloud获取API Token，通过指定提示词、模型、清晰度、时长等参数生成视频。支持自定义首尾帧、模板特效、角色ID及视频扩展生成。API提供异步回调功能，任务完成后通过callback_url推送结果，并附有错误处理说明。
延伸解读
异步回调与轮询模式的选择
视频生成耗时约1-2分钟，API支持两种获取结果的方式：设置callback_url异步回调，或设置async为true后轮询任务查询接口。回调模式需自行搭建HTTP服务接收POST JSON，并注意task_id关联；轮询模式则无需回调地址，但需控制查询频率。开发者可根据自身架构和稳定性要求选择合适模式。
模板特效与角色ID的扩展能力
除基础文生视频外，API还支持通过template_id指定特效模板（如“成为肌肉猛男”“黑悟空引擎”等），通过asset_id使用自定义角色，以及通过action=extend对已有视频进行扩展。这些功能可组合使用，但需注意模板和角色ID需通过其他API或文档获取，且部分模板仅支持特定清晰度。
参数细节与错误处理注意事项
请求参数中prompt为必填，quality默认540p但示例返回360p，实际以请求为准。错误响应包含success=false及error对象，如提示包含艺术家名字等违规内容。建议开发者检查错误码和message，并利用trace_id追踪问题。此外，seed可固定随机性，但示例中seed为0，实际使用需自行测试。
Q&A
如何获取Pixverse视频生成API的Token？
需要到Ace Data Cloud控制台获取API Token，首次申请会赠送免费额度。
Pixverse视频生成API支持哪些参数？
主要参数包括model（默认v3.5）、action（generate或extend）、prompt（必填）、style、motion、quality、duration、image_url、aspect_ratio、seed、template_id、callback_url、async等。
如何自定义首尾帧生成视频？
在请求参数中添加frame字段，传入首尾帧图片链接数组，例如："frame": ["https://cdn.acedata.cloud/c7zzmb.png","https://cdn.acedata.cloud/fqd8br.png"]。
如何使用模板特效生成视频？
在请求参数中添加template_id字段，指定模板ID，例如"template_id": 302325299651648，即可使用对应的模板特效。
如何对已生成的视频进行扩展生成？
将action参数设置为extend，并传入需要扩展的视频ID（video_id），例如："action": "extend", "video_id": 317989274748288。
如何根据角色ID生成视频？
需要先通过Pixverse Character API获取角色ID（asset_id），然后在生成视频时传入asset_id参数，例如"asset_id": 318174747147968。
Pixverse视频生成API支持哪些异步回调方式？
支持通过callback_url字段指定回调URL，任务完成后会通过POST JSON发送结果；也可以设置async为true，接口立即返回task_id，然后通过轮询获取结果。
Pixverse视频生成API的错误处理是怎样的？
发生错误时，API会返回success为false，并包含error对象，其中包含错误代码和消息，例如"code": "forbidden", "message": "Song Description contained artist name: eminem"。
