一键音乐MV(Music Video)

Oneclick 音乐 MV API 文档

1. 产品介绍

一句话总结： 零门槛的“音乐视觉化”神器，一键将音频变爆款 MV。

核心功能与技术亮点

• 极简输入： 支持纯音乐或带人声歌曲，可选上传模特或角色图片，精准控制主角脸型、发型。
• 支持对口型： 支持对口型生成模式，精准匹配音频内容与人物口型，贴合演唱节奏与情绪，自然还原真人演唱的视觉效果，适配多元曲风与画面风格。
• 多元视觉风格： 内置 15 种画面风格，覆盖真人演唱、真人叙事、2D/3D 动画、Lofi 复古、像素风等，贴合短视频审美。
• 国际化多语种： AI 自动识别或生成歌词字幕，支持中文、英文及多种海外语言。
• 核心优势： 极简交互链路、极低生成成本、极高镜头画面稳定性，以及业界顶尖的歌词与画面卡点能力。

展示素材

• Oneclick showcase
• Oneclick MV 风格前端展示素材

计费与并发

项目	说明
支持分辨率	720p、1080p
720p 计费	15 credits/s，时长向上取整
1080p 计费	720p 的 1.5 倍
并发占用	每次调用占用 10

2. 调用流程

1. 通过 /openapi/v2/media/upload 上传音频，获取音频 ID。
2. 调用 /openapi/v2/audio/verification，完成音频审核。
3. 音频审核通过后，调用 /openapi/v2/video/music_mv_agent/generate 生成音乐 MV。
4. 获取返回的 video_id，通过 /openapi/v2/video/result/{video_id} 查询视频结果及视频 URL。

3. 公共请求 Header

音频校验和音乐 MV 生成接口均使用以下 Header。

字段	类型	必填	说明或取值
API-KEY	string	是	Pixverse API Key，客户注册后获得的唯一 Key
Ai-trace-id	string	是	每个链路任务新建的 ID
Content-Type	string	是	application/json

4. 音频校验接口

4.1 接口信息

项目	说明
支持环境	国内 ✅、海外 ✅
业务能力	对上传的音频进行审核，同步返回审核结果
请求方式	POST
请求路径	/openapi/v2/audio/verification

4.2 请求 Body

字段	类型	必填	说明	校验规则
audio_media_id	uint64	是	上传接口返回的音频 ID；原始示例为 "music_id": 1111	必须是当前账号上传的音频

4.3 请求示例

curl --location --request POST 'https://app-api.pixverse.ai/openapi/v2/audio/verification' \
  --header 'API-KEY: sk-xxxxxxxxxxx' \
  --header 'Ai-trace-id: xxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "audio_media_id": 405833376854443
  }'

4.4 成功响应

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {}
}

4.5 错误响应

含义	ErrCode	ErrMsg
音频 ID 为空	400017	Required field audio_media_id are missing or empty.
音频 ID 不存在	400013	Invalid field type or value. Please verify your input data.
音频非本账号创建	500047	audio_media_id: The provided media is invalid — the type may be incorrect, or the resource is no longer available.
传入 ID 格式错误	500047	audio_media_id: The provided media is invalid — the type may be incorrect, or the resource is no longer available.
音频内容违规（英文）	500063	The text you entered contains sensitive information. Please re-enter.
音频内容违规（中文）	500063	输入的内容不符合平台规范，请重新输入

错误响应示例：

{
  "ErrCode": 400017,
  "ErrMsg": "Required field audio_media_id are missing or empty."
}

5. 音乐 MV 生成接口

5.1 接口信息

项目	说明
支持环境	国内 ✅、海外 ✅
业务能力	生成音乐 MV
请求方式	POST
请求路径	/openapi/v2/video/music_mv_agent/generate
并发占用	10

5.2 请求 Body

字段	类型	必填	说明与校验规则
mv_agent_type	string	是	使用 vibe_mv_v3_custom
audio_media_id	uint64	是	音频上传后返回的 ID；原始示例为 "media_id": 1111。须先通过音频校验。参数说明要求文件不超过 100 MB，时长为 10 秒至 6 分钟；大小限制与错误示例存在差异，见第 2 节
image_references	array	否	角色图片，当前仅支持单图。支持 JPG、PNG、WebP，尺寸不超过 10000 × 10000 像素，文件大小不超过 20 MB
style_img_references	array	否	仅在 mv_style=Custom 时传入风格图片，当前仅支持单图，格式、尺寸和大小限制同角色图片。未传时使用角色图片作为风格参考；自定义风格下两种图片引用不能同时为空
music_style	string	否	音乐风格，见下方枚举，不区分大小写；为空时由算法处理
mv_style	string	否	MV 画面风格，见下方枚举，不区分大小写；为空时由算法处理
aspect_ratio	string	否	16:9、9:16、1:1、4:3、3:4，默认 16:9
quality	string	否	720p、1080p，默认 720p
lyric_text	string	否	歌词内容，建议保留标点或换行
caption_switch	boolean	否	字幕开关，默认 false
lip_sync_switch	boolean	否	对口型开关，true 开启，false 关闭，默认 false。纯音乐开启对口型会生成失败并返回错误
lyric_timestamp	JSON object	否	1.
歌词时间戳里面的0秒表示的是audio起始时间

时间戳单调递增（每一个新start时间不能早于上一个end时间，当前不支持叠字情况）

时间戳需小于等于audio时长（会校验歌词时间戳长度不得超过音频时长）

words数量限制5000，拼接后长度小于5000

跟lyric_text同时传入时，优先用lyric_timestamp

{
"words": [
{
"start": 0.0,
"end": 0.32,
"word": "Who"
},
{
"start": 0.32,
"end": 0.64,
"word": "be"
}
]
} |

5.3 风格枚举

音乐风格 music_style：

Pop / Rock / Hip Hop / R&B / Jazz / Reggae / Country / Folk /
Electronic / Classical / Soul / Funk / Metal / Ambient / Others

MV 画面风格 mv_style：

Custom / Cinematic / Lo-fi / Dreamscape / Woolen Felt / Candy /
Golden Age / Voxel / Retro Game / Claymation / Woodland Tale /
Impressionism / Decadence / Futuristic / Chromatic Clash / Holiday

其中，Custom 为自定义风格，其余为 15 种内置风格。

5.4 图片引用格式

角色图片：

{
  "image_references": [
    {
      "img_id": 164913710,
      "ref_name": "角色图片"
    }
  ]
}

风格图片：

{
  "style_img_references": [
    {
      "img_id": 164913711,
      "ref_name": "风格图片"
    }
  ]
}

当 mv_style=Custom 时：

• 未上传 style_img_references，则使用 image_references 作为风格参考。
• image_references 与 style_img_references 不能同时为空。

5.5 歌词时间戳

{
  "lyric_timestamp": {
    "words": [
      {
        "start": 0.0,
        "end": 0.32,
        "word": "Who"
      },
      {
        "start": 0.32,
        "end": 0.64,
        "word": "be"
      }
    ]
  }
}

校验规则：

1. 时间单位为秒，0 表示音频起始时间。
2. 时间戳必须单调递增：每个新 start 不能早于上一个 end，当前不支持叠字。
3. 时间戳必须小于或等于音频时长。
4. words 数量不超过 5000，拼接后的文本长度小于 5000。
5. 与 lyric_text 同时传入时，优先使用 lyric_timestamp。

5.6 请求示例

以下示例保留主要参数，歌词为节选；JSON 中已移除注释，以便直接使用。

curl --location --request POST 'https://app-api.pixverse.ai/openapi/v2/video/music_mv_agent/generate' \
  --header 'API-KEY: sk-xxxxxxxxxxx' \
  --header 'Ai-trace-id: xxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "mv_agent_type": "vibe_mv_v3_custom",
    "audio_media_id": 404796051111573,
    "image_references": [
      {
        "img_id": 164913710,
        "ref_name": "角色图片"
      }
    ],
    "style_img_references": [
      {
        "img_id": 164913711,
        "ref_name": "风格图片"
      }
    ],
    "music_style": "Jazz",
    "mv_style": "Custom",
    "aspect_ratio": "16:9",
    "quality": "720p",
    "lyric_text": "The city breathes in velvet hush\nStreetlights bleed soft molten gold\nMy footsteps hum a quiet rush\nWhere winter air turns warm and old",
    "caption_switch": true,
    "lip_sync_switch": true
  }'

5.7 成功响应

接口成功返回 video_id 后，通过 /openapi/v2/video/result/{video_id} 获取视频结果及视频 URL。

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 311156303940608,
    "credits": 1000
  }
}

5.8 错误响应

下表完整保留原始错误码与错误消息。除另行标注外，响应示例包含 ErrCode 与 ErrMsg 两个字段。

含义	ErrCode	ErrMsg
音频未审核，需先调用音频校验接口	701020	The audio content has not been verified. Please call the audio verification interface first.
音频审核未通过	500063	The text you entered contains sensitive information. Please re-enter.
mv_agent_type 不在指定枚举内	400017	Invalid value for mv_agent_type
视频比例错误	400017	Invalid value for aspect_ratio.
视频清晰度错误	400017	Invalid value for quality.
音频文件大小超限	400017	Audio file size exceeds the 15MB limit.
音频时长超过 360 秒	400017	The audio duration exceeds the 360-second limit.（响应另含 "Resp": null）
音频时长无效	400017	Invalid value for duration.
mv_style 不在指定枚举内	400017	Invalid value for mv_style.
music_style 不在指定枚举内	400017	Invalid value for music_style.
音频 ID 为空	400017	Required field audio_media_id are missing or empty.
音频非本账号资源	500047	audio_media_id: The provided media is invalid — the type may be incorrect, or the resource is no longer available.
音频 ID 不存在	500047	audio_media_id: The provided media is invalid — the type may be incorrect, or the resource is no longer available.
图片超过一张	400017	Invalid value for img_references.
图片 ID 为空	400017	Invalid value for img_id.
图片非本账号资源	701009	Invalid query. You can only query your own generated or uploaded content.
图片 ID 不存在	400032	invalid img id
自定义风格下，角色图片和风格图片同时为空	400017	image_references and style_img_references cannot both be empty when mv_agent_type is vibe_mv_v3_custom and mv_style is custom.
纯音乐开启对口型	400017	No lyrics were detected in the audio. Lip sync MV requires vocals with recognizable lyrics.
通用提示词超过 5000 字符	400017	music_style / mv_prompt must be within 5000 characters
歌词审核拦截	500063	The text you entered contains sensitive information. Please re-enter.
音频审核拦截	500063	The content you entered contains sensitive information. Please re-enter.
免费用户因并发限制不可用	500044	Reached the limit for concurrent generations.

音频未审核：

{
  "ErrCode": 701020,
  "ErrMsg": "The audio content has not been verified. Please call the audio verification interface first."
}

音频时长超限：

{
  "ErrCode": 400017,
  "ErrMsg": "The audio duration exceeds the 360-second limit.",
  "Resp": null
}

自定义风格缺少图片：

{
  "ErrCode": 400017,
  "ErrMsg": "image_references and style_img_references cannot both be empty when mv_agent_type is vibe_mv_v3_custom and mv_style is custom."
}

纯音乐开启对口型：

{
  "ErrCode": 400017,
  "ErrMsg": "No lyrics were detected in the audio. Lip sync MV requires vocals with recognizable lyrics."
}