> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音乐 Webhook

> 音乐生成任务完成时自动接收回调通知

除了轮询[查询音乐详情](https://docs.vidgo.ai/zh/api-manual/music-series/query-music-detail.md)接口，你还可以在提交音乐生成任务时提供 `callback_url`，在生成完成时自动接收通知。

## 工作原理

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

## 回调请求

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

### 请求头

```
Content-Type: application/json
```

### 请求体结构

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

> [!NOTE]
>
> `files` 数组的内容取决于创建任务的模型。详见下方的[响应字段](#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 字符串。[查看详情](#separate-vocals) |
| `upload-and-separate-vocals` | `vocal_removal` | string (JSON) | 包含分离后音轨 URL 的 JSON 字符串。[查看详情](#upload-and-separate-vocals) |
| `stem-split` | `stem_split` | string (JSON) | 包含完整音轨分离 URL 的 JSON 字符串。[查看详情](#stem-split) |
| `generate-music-cover` | `generate_cover` | string (JSON) | 包含生成封面图的 JSON 字符串。[查看详情](#generate-music-cover) |
| `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 等）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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
  }
}
```

### 失败任务

```json theme={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 次重试均失败后，不再继续重试

> [!WARNING]
>
> 如果所有重试均失败，你仍然可以通过轮询[查询音乐详情](https://docs.vidgo.ai/zh/api-manual/music-series/query-music-detail.md)接口获取结果。

## 安全最佳实践

> [!TIP]
>
> **验证请求**：建议添加签名验证机制，确保请求来自 Vidgo API

> [!TIP]
>
> **幂等性**：将 Webhook 处理程序设计为幂等，以应对重复投递

> [!TIP]
>
> **异步处理**：异步处理回调并尽快返回 200，避免超时

> [!TIP]
>
> **日志记录**：记录所有 Webhook 请求，便于调试和监控


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.