上传图片
POST
/openapi/v2/image/upload
上传图片
img_id，后续在图生视频、视频模板、首尾帧、多主体多参考图、多帧生成等接口中使用。适用场景
| 使用场景 | 后续接口 |
|---|---|
| 单图生成视频 | 图生视频 |
| 模板或特效生成 | 视频模板 |
| 控制开始和结束画面 | 首尾帧生成视频 |
| 多角色 / 多参考图 | 多主体多参考图 |
| 多帧过渡 | 多帧 Multi-transition 生成视频 |
接入流程
准备图片文件或图片 URL
-> 调用上传图片 API
-> 获取 img_id
-> 在图生 / 模 板 / 首尾帧等接口中传入 img_id 或 img_ids接口地址
请求参数
| 参数 | 类型 | 是否必填 | 示例 | 说明 | 限制条件备注 |
|---|---|---|---|---|---|
image | file | 条件必填 | /path/to/image.png | 本地图片文件，与 image_url 二选一 | 支持 png、webp、jpeg、jpg；最大 20MB；图片最长边建议不超过 10000px |
image_url | string | 条件必填 | https://example.com/image.png | 公网可访问的图片 URL，与 image 二选一 | URL 需可公网访问；资源本身仍需满足图片格式、大小和像素限制 |
素材限制
| 类型 | 支持格式 / mime-type | 限制条件备注 |
|---|---|---|
| 图片格式 | png、webp、jpeg、jpg | 文件需为真实图片格式，后缀和内容类型建议保持一致 |
| mime-type | image/jpeg、image/jpg、image/png、image/webp | 通过 URL 上传时，服务端需要能识别对应内容类型 |
| 文件大小与像素 | 最大 20MB；最长边10,000px 以内图片 | 超过限制可能上传失败，建议上传前压缩或调整分辨率 |
cURL 示例：上传本地图片
cURL 示例：通过图片 URL 上传
字段填写备注
字段填写备注
| 字段类型 | 填写建议 |
|---|---|
API-KEY | 使用正式 API Key，不要放在 URL Query 中。 |
Ai-trace-id | 每次请求使用新的 UUID；同一个值重复请求可能被识别为重复任务。 |
image / image_url | 二选一。本地上传图片时使用 image；通过 URL 上传图片时使用 image_url。 |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
Resp.img_id | integer | 图片 ID，后续图生、模板、首尾帧、多主体等接口使用 |
Resp.img_url | string | 上传后的图片地址 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"img_id": 0,
"img_url": "https://media.pixverseai.cn/openapi/xxxyyyzzz1122.jpeg"
}
}请求参数
Header 参数
Body 参数multipart/form-data必填
返回响应
请求示例请求示例
Shell
curl --location 'https://app-api.pixverseai.cn/openapi/v2/image/upload' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: 550e8400-e29b-41d4-a716-446655440000' \
--form 'image=@""' \
--form 'image_url="https://example.com/image.jpg"'响应示例响应示例
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"property1": "string",
"property2": "string"
}
}修改于 2026-09-04 06:46:31