音乐 Webhook

除了轮询查询音乐详情接口，你还可以在提交音乐生成任务时提供 callback_url，在生成完成时自动接收通知。

工作原理

提交时附带回调 URL：在音乐生成请求中加入 callback_url 参数
任务处理：Vidgo API 处理你的音乐生成任务
接收通知：当任务状态变为 finished 或 failed 时，Vidgo API 会向你的回调 URL 发送 POST 请求
处理结果：你的服务器会收到完整的任务数据，包括生成的文件

回调请求

任务完成时，Vidgo API 会向你的回调 URL 发送 POST 请求：

请求头

Content-Type: application/json

请求体结构

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [...],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

files 数组的内容取决于创建任务的模型。详见下方的响应字段。

files 数据响应字段

files 数组的内容取决于创建任务的模型。

模型	字段	类型	说明
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`audio_id`	string	音频文件的唯一标识
↑	`audio_url`	string	音频文件的直接下载 URL
↑	`image_url`	string	封面图 URL
↑	`title`	string	曲目标题
↑	`tags`	string	风格标签
↑	`duration`	number	音频时长（秒）
↑	`prompt`	string	生成时使用的提示词
`get-timestamped-lyrics`	`timestampe_lyrics`	string	带时间戳的歌词
`generate-lyrics`	`title`	string	歌词标题
↑	`text`	string	完整歌词内容
`boost-music-style`	`style`	string	增强后的音乐风格
`convert-to-wav`	`wav_url`	string	转换后 WAV 文件的 URL
`separate-vocals`	`separate_vocals`	string (JSON)	包含分离后音频 URL 的 JSON 字符串。查看详情
`upload-and-separate-vocals`	`vocal_removal`	string (JSON)	包含分离后音轨 URL 的 JSON 字符串。查看详情
`stem-split`	`stem_split`	string (JSON)	包含完整音轨分离 URL 的 JSON 字符串。查看详情
`generate-music-cover`	`generate_cover`	string (JSON)	包含生成封面图的 JSON 字符串。查看详情
`generate-persona`	`persona_id`	string	生成的 persona 标识
`create-music-video`	`video_url`	string	生成的视频 URL

JSON 字段详情

separate-vocals

separate_vocals 字段：

vocal_url - 提取出的人声音轨 URL
instrumental_url - 伴奏音轨 URL

upload-and-separate-vocals

vocal_removal 字段：

bass - 贝斯音轨 URL
drums - 鼓音轨 URL
piano - 钢琴音轨 URL
guitar - 吉他音轨 URL
vocals - 人声音轨 URL
other - 其他音频元素 URL

stem-split

stem_split 字段：

backing_vocals_url - 和声 URL
bass_url - 贝斯音轨 URL
brass_url - 铜管乐器 URL
drums_url - 鼓音轨 URL
fx_url - 音效 URL
guitar_url - 吉他音轨 URL
keyboard_url - 键盘音轨 URL
percussion_url - 打击乐音轨 URL
strings_url - 弦乐音轨 URL
synth_url - 合成器音轨 URL
vocal_url - 主唱人声 URL
woodwinds_url - 木管乐器音轨 URL

generate-music-cover

generate_cover 是包含封面图对象的 JSON 数组：

file_url - 生成的封面图 URL
file_type - 文件类型（例如 “image”）

回调示例

音乐生成（generate-music、extend-music 等）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
        "audio_url": "https://file.goseaapp.com/audio/8FDN1I7M7Q68DDG8/audio_62e4542a.mp3",
        "image_url": "https://file.goseaapp.com/audio/8FDN1I7M7Q68DDG8/cover_62e4542a.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 240.0,
        "prompt": ""
      },
      {
        "audio_id": "8e755734-a840-4c13-beac-b9f1044979ca",
        "audio_url": "https://file.goseaapp.com/audio/8FDN1I7M7Q68DDG8/audio_8e755734.mp3",
        "image_url": "https://file.goseaapp.com/audio/8FDN1I7M7Q68DDG8/cover_8e755734.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 130.0,
        "prompt": ""
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

带时间戳的歌词（get-timestamped-lyrics）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "timestampe_lyrics": "[00:00.00] First line of lyrics\n[00:05.23] Second line of lyrics"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

生成歌词（generate-lyrics）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "title": "Peaceful Piano Meditation",
        "text": "Peaceful Piano Meditation lyrics content..."
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

音乐风格增强（boost-music-style）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "style": "Enhanced music style result"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

WAV 转换（convert-to-wav）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "wav_url": "https://file.goseaapp.com/audio/8FDN1I7M7Q68DDG8/output.wav"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

人声分离（separate-vocals）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "separate_vocals": "{\"vocal_url\": \"https://file.goseaapp.com/audio/vocals.mp3\", \"instrumental_url\": \"https://file.goseaapp.com/audio/instrumental.mp3\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

上传并分离人声（upload-and-separate-vocals）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "vocal_removal": "{\"bass\": \"https://file.goseaapp.com/audio/bass.mp3\", \"drums\": \"https://file.goseaapp.com/audio/drums.mp3\", \"piano\": \"https://file.goseaapp.com/audio/piano.mp3\", \"guitar\": \"https://file.goseaapp.com/audio/guitar.mp3\", \"vocals\": \"https://file.goseaapp.com/audio/vocals.mp3\", \"other\": \"https://file.goseaapp.com/audio/other.mp3\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

音轨分离（stem-split）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "stem_split": "{\"backing_vocals_url\": \"\", \"bass_url\": \"\", \"brass_url\": \"\", \"drums_url\": \"\", \"fx_url\": \"\", \"guitar_url\": \"\", \"keyboard_url\": \"\", \"percussion_url\": \"\", \"strings_url\": \"\", \"synth_url\": \"\", \"vocal_url\": \"\", \"woodwinds_url\": \"\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

音乐封面图（generate-music-cover）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "generate_cover": "[{\"file_url\": \"https://file.goseaapp.com/audio/cover_1.png\", \"file_type\": \"image\"}, {\"file_url\": \"https://file.goseaapp.com/audio/cover_2.png\", \"file_type\": \"image\"}]"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

生成 Persona（generate-persona）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "persona_id": "persona_abc123"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

音乐视频（create-music-video）

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "video_url": "https://file.goseaapp.com/video/8FDN1I7M7Q68DDG8/music_video.mp4"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

失败任务

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "failed",
    "files": [],
    "created_time": "2025-11-25T08:50:13",
    "error_message": "The prompt violates our content policy"
  }
}

要求

你的回调接口必须满足以下要求：

仅限 HTTPS：必须使用 HTTPS 协议（不支持 HTTP）
URL 最大长度：2048 个字符
响应超时：必须在 10 秒内响应
成功响应：应返回 HTTP 200-299 状态码
禁止内网 IP：不能使用私有或内网 IP 地址（例如 192.168.x.x、10.x.x.x）
公网可访问：必须能从互联网公开访问

重试策略

如果你的回调接口未响应或返回错误：

重试次数：自动重试 3 次
重试间隔：分别在 1 秒、2 秒和 4 秒后重试
最终失败：3 次重试均失败后，不再继续重试

如果所有重试均失败，你仍然可以通过轮询查询音乐详情接口获取结果。

安全最佳实践

验证请求：建议添加签名验证机制，确保请求来自 Vidgo API

幂等性：将 Webhook 处理程序设计为幂等，以应对重复投递

异步处理：异步处理回调并尽快返回 200，避免超时

日志记录：记录所有 Webhook 请求，便于调试和监控

概览

任务管理

文件管理

账户管理

常见问题

工作原理

回调请求

请求头

请求体结构

files 数据响应字段

JSON 字段详情

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover

回调示例

音乐生成（generate-music、extend-music 等）

带时间戳的歌词（get-timestamped-lyrics）

生成歌词（generate-lyrics）

音乐风格增强（boost-music-style）

WAV 转换（convert-to-wav）

人声分离（separate-vocals）

上传并分离人声（upload-and-separate-vocals）

音轨分离（stem-split）

音乐封面图（generate-music-cover）

生成 Persona（generate-persona）

音乐视频（create-music-video）

失败任务

要求

重试策略

安全最佳实践

​工作原理

​回调请求

​请求头

​请求体结构

​files 数据响应字段

​JSON 字段详情

​separate-vocals

​upload-and-separate-vocals

​stem-split

​generate-music-cover

​回调示例

​音乐生成（generate-music、extend-music 等）

​带时间戳的歌词（get-timestamped-lyrics）

​生成歌词（generate-lyrics）

​音乐风格增强（boost-music-style）

​WAV 转换（convert-to-wav）

​人声分离（separate-vocals）

​上传并分离人声（upload-and-separate-vocals）

​音轨分离（stem-split）

​音乐封面图（generate-music-cover）

​生成 Persona（generate-persona）

​音乐视频（create-music-video）

​失败任务

​要求

​重试策略

​安全最佳实践

工作原理

回调请求

请求头

请求体结构

files 数据响应字段

JSON 字段详情

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover

回调示例

音乐生成（generate-music、extend-music 等）

带时间戳的歌词（get-timestamped-lyrics）

生成歌词（generate-lyrics）

音乐风格增强（boost-music-style）

WAV 转换（convert-to-wav）

人声分离（separate-vocals）

上传并分离人声（upload-and-separate-vocals）

音轨分离（stem-split）

音乐封面图（generate-music-cover）

生成 Persona（generate-persona）

音乐视频（create-music-video）

失败任务

要求

重试策略

安全最佳实践