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

# 提交音乐动作

> POST 一个 Suno 音乐动作：创作、续写、编辑、分轨、分析或导出曲目

## 概览

`POST /api/v1/music/{action}` 是 [Suno](/zh/models/suno) 音乐的主入口，路径中的 `action` 为 33 个动作之一。每个动作都会创建一个 `suno` 模型的异步任务：保存 `data.task_id`，再通过 [`POST /api/v1/task/status`](/zh/api-reference/endpoint/task-status) 查询直到任务结束。每次调用计费一次，各动作积分见 [Suno 计费](/zh/models/suno)。

`POST /api/v1/task/submit/suno` 仍然可用，等同于 `generate` 动作。

```bash theme={null}
curl --fail-with-body --silent --show-error \
  -X POST https://api.wizzx.ai/api/v1/music/generate \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "custom": true,
    "prompt": "[Verse]\n雨夜里霓虹闪烁的街道",
    "title": "Midnight Drive",
    "style": "synthwave, female vocal"
  }'
```

响应沿用常规的提交格式，并额外返回 `action`：

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11",
    "model_key": "suno",
    "action": "generate",
    "credits_deducted": 60
  },
  "request_id": "0d9d7b8e-51f6-4a1e-8d0e-9b7c2a6f4c33"
}
```

## 通用规则

* **严格字段。** 每个动作只接受下文为它列出的字段。传入该动作不接受的音乐字段会返回 HTTP 422 `validation_failed`，例如 `music action bpm does not accept version`。不需要的字段请直接省略。
* 未知动作返回 HTTP 404 `music_action_not_found`。
* 文本长度按 Unicode 字符计算。音频 URL 必须是公网可访问的 HTTP(S) 地址，最多 2,048 个字符。
* 之前的任务只能通过 Wizzx `task_id` 引用，见下方「引用已有任务」。
* 音乐动作与提交接口共用限流。参数校验和来源任务校验失败时，不会预扣任何积分。

## 通用字段

以下字段在所有接受它们的动作中含义相同。

| 字段 | 类型 | 规则 |
| - | - | - |
| `prompt` | string | 自定义模式下为歌词，最多 5,000 个字符。`generate` 灵感模式的歌曲描述、`lyrics` 的主题与 `sounds` 的音效描述最多 3,000 个字符 |
| `gpt_description` | string | `generate` 以外动作在灵感模式（`custom: false`）下的歌曲描述，最多 3,000 个字符 |
| `custom` | boolean | 自定义（歌词）模式开关，见下方「自定义模式与灵感模式」 |
| `instrumental` | boolean | `true` 表示无人声。不能与 `vocal_gender` 同时使用 |
| `version` | string | `v6`（默认）、`v6-wild` 或 `v6-mini`，不区分大小写，价格相同 |
| `custom_model_task_id` | string | 你已完成的 `create-model` 任务的 `task_id`。用于替代 `version`；不能与 `version` 或 `persona_task_id` 同时使用 |
| `persona_task_id` | string | 你已完成的 `persona` 或 `create-voice` 任务的 `task_id`。仅自定义模式 |
| `title` | string | 最多 80 个字符 |
| `style` | string | 风格标签，最多 1,000 个字符 |
| `negative_tags` | string | 需要避开的风格，最多 1,000 个字符 |
| `style_weight`、`weirdness`、`audio_weight` | number | 0–1；`0` 是有效值 |
| `vocal_gender` | string | `Male` 或 `Female`（也接受 `m`、`f`）。不能与 `instrumental: true` 同时使用 |
| `auto_lyrics` | boolean | 仅自定义模式 |
| `variety` | string | `off`、`normal`、`high`、`extra` 或 `max` |
| `max_mode` | boolean | 更高质量，价格翻倍。在有模式开关的动作上需要自定义模式 |
| `audio_format` | string | `mp3`、`m4a` 或 `wav` |
| `duration` | integer | 目标时长 10–360 秒，实际时长可能不同；不影响价格 |
| `task_id` | string | 来源任务，见下方「引用已有任务」 |
| `audio_index` | integer | 1–20，默认 `1`：来源曲目的 `result.tracks[].index` |

下文动作表格使用以下简称：

* **模型选择**：`version` 或 `custom_model_task_id`
* **风格字段**：`title`、`style`、`negative_tags`
* **权重**：`style_weight`、`weirdness`、`audio_weight`
* **模式字段**：`custom`、`prompt`、`gpt_description`

## 自定义模式与灵感模式

部分动作可以在自定义模式（自己写歌词和风格）与灵感模式（由 Suno 根据描述创作）之间切换。

| 动作 | 模式如何确定 |
| - | - |
| `generate` | `custom` 默认 `false`。灵感模式：`prompt` 为必填的歌曲描述。自定义模式：`prompt` 为歌词，除非 `instrumental` 为 `true`，否则必填；自定义纯音乐需要 `prompt` 或 `style` |
| `upload-cover` | `custom` **必填**。`false` 需要 `gpt_description`；`true` 需要 `prompt`，除非 `instrumental` 为 `true` |
| `extend` | `custom` 默认 `true`。`false` 需要 `gpt_description` |
| `cover`、`add-vocals`、`add-instrumental`、`add-stem`、`mashup`、`sample` | 省略 `custom` 时自动推断：有 `prompt` 视为自定义；否则有 `gpt_description` 视为灵感；否则有 `style` 或 `title` 视为自定义；都没有则返回 422。`mashup` 与 `sample` 在自定义模式下需要 `prompt`，除非 `instrumental` 为 `true` |
| `upload-extend` | 始终为自定义模式，没有 `custom` 字段 |

灵感模式下，`generate` 拒绝 `title`、`style`、`negative_tags`、`auto_lyrics`、`persona_task_id`、`duration` 与 `max_mode`；其他动作拒绝 `prompt`、`title`、`style`、`negative_tags`、`auto_lyrics`、`persona_task_id`、`duration`、`max_mode`、`style_weight` 与 `audio_weight`。自定义模式下拒绝 `gpt_description`。

## 引用已有任务

许多动作基于你已经生成的曲目：

* `task_id` + `audio_index` 选择一首曲目。`audio_index` 是该曲目在来源任务 `result.tracks` 中从 1 开始的 `index`，默认 `1`。
* `mashup` 改用 `task_ids`（正好两个任务）与 `audio_indexes`（两个元素，默认 `[1, 1]`）。
* `custom_model_task_id` 必须指向已完成的 `create-model` 任务，`persona_task_id` 必须指向已完成的 `persona` 或 `create-voice` 任务。

被引用的任务必须是你自己的、状态为 `SUCCEEDED` 的 `suno` 任务。只有产出曲目的动作才能作为曲目来源：`generate`、`inspo`、`sounds`、`upload`、`upload-cover`、`upload-extend`、`extend`、`cover`、`remaster`、`stems`、`stems-all`、`add-vocals`、`add-instrumental`、`add-stem`、`replace-section`、`remove-section`、`crop`、`fade-in`、`fade-out`、`adjust-speed`、`concat`、`mashup` 与 `sample`。歌词、风格、分析、Persona、模型、声音、视频与下载结果不能作为来源。

部分动作要求特定类型的来源：

| 动作 | 来源任务必须是 |
| - | - |
| `add-vocals`、`add-instrumental`、`sample` | `upload` 任务 |
| `concat` | `extend` 任务 |

扣费前，网关还会检查 `audio_index` 在来源任务中存在，且 `continue_at`、`end_s`、`fade_duration` 不超出来源曲目时长。任一检查失败都会返回 HTTP 422，不会预扣积分。

<Note>
  2026 年 10 月 15 日之前完成的任务没有 `result` 对象。它们仍可作为来源，但无法提前校验曲目序号与时间；超出范围的值会导致任务失败，积分会退回。
</Note>

## 动作

所有动作的输出都在任务状态的 [`result`](/zh/api-reference/endpoint/task-status) 对象中返回。

### 创作

| 动作 | 必填 | 可选 | 结果 |
| - | - | - | - |
| `generate` | `prompt`（自定义模式纯音乐除外，见模式规则） | `custom`、`instrumental`、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format`、`duration` | `tracks`，通常两首 |
| `inspo` | `audio_urls`：1–4 个公网参考音频 URL | `prompt`（歌词）、模型选择、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format` | `tracks` |
| `sounds` | `prompt`：音效描述 | `version`、`sound_type`（`one-shot` 或 `loop`）、`bpm`（整数 1–300）、`key`（`C` 到 `B`，升号写法如 `F#`，小调加 `m` 如 `C#m`）、`audio_format` | `tracks` |
| `lyrics` | `prompt`：主题 | `lyrics_model`（`classic` 或 `remi`） | `lyrics` |
| `upsample-tags` | `style` | – | `style`（增强后） |
| `upload` | `audio_url` | – | `tracks`；曲目可能没有 `audio_url`。该任务可作为 `add-vocals`、`add-instrumental`、`sample` 的来源 |
| `upload-cover` | `audio_url`（短于 8 分钟）、`custom` | 模式字段、`instrumental`、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format`、`duration` | `tracks` |
| `upload-extend` | `audio_url`、`continue_at`（至少 1 秒） | `prompt`（歌词）、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format`、`duration` | `tracks` |
| `create-model` | `name`（最多 80 个字符）、`audio_urls`：6–24 个公网音频 URL | – | `model_id`。把本任务的 `task_id` 作为 `custom_model_task_id` 使用。可能需要约 20 分钟 |
| `create-voice` | `audio_url`（MP3 或 WAV）：不带伴奏的干净人声录音 | – | `persona_id`；把本任务的 `task_id` 作为 `persona_task_id` 使用 |

### 基于已有曲目

除特别说明外，以下动作都接受 `task_id`（必填）与 `audio_index`（可选）。

| 动作 | 除 `task_id` 外必填 | 可选 | 来源 | 结果 |
| - | - | - | - | - |
| `extend` | `continue_at`：至少 1 秒且小于曲目时长 | 模式字段（`custom` 默认 `true`）、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format`、`duration` | 任意曲目 | `tracks` |
| `concat` | – | `audio_format` | `extend` 任务 | `tracks`：拼接后的完整歌曲 |
| `cover` | 模式（自动推断，见模式规则） | 模式字段、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`variety`、`max_mode`、`audio_format`、`duration` | 任意曲目 | `tracks` |
| `remaster` | – | `variation_category`（`subtle`、`normal` 或 `high`）、`audio_format` | 任意曲目 | `tracks` |
| `add-vocals` | 模式（自动推断，见模式规则） | 模式字段、模型选择、风格字段、权重、`vocal_gender`、`variety`、`max_mode`、`audio_format` | `upload` 任务 | `tracks` |
| `add-instrumental` | 模式（自动推断，见模式规则） | 与 `add-vocals` 相同 | `upload` 任务 | `tracks` |
| `add-stem` | 模式（自动推断，见模式规则） | 模式字段、模型选择、风格字段、权重、`variety`、`max_mode`、`audio_format` | 任意曲目 | `tracks` |
| `mashup` | `task_ids`：正好两个任务，替代 `task_id`；模式（自动推断） | `audio_indexes`（两个元素，默认 `[1, 1]`）、模式字段、`instrumental`、模型选择、`persona_task_id`、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format` | 两首曲目 | `tracks` |
| `sample` | `start_s`、`end_s`；模式（自动推断） | 模式字段、`instrumental`、模型选择、风格字段、权重、`vocal_gender`、`auto_lyrics`、`variety`、`max_mode`、`audio_format` | `upload` 任务 | `tracks` |
| `persona` | `name`（最多 80 个字符） | `description`（最多 1,000 个字符）、`style`、`start_s` / `end_s`（人声片段） | 任意曲目 | `persona_id`。把本任务的 `task_id` 作为 `persona_task_id` 使用 |

### 编辑

所有编辑动作都接受 `task_id`（必填）与 `audio_index`（可选），来源可以是任意曲目。

| 动作 | 除 `task_id` 外必填 | 可选 | 结果 |
| - | - | - | - |
| `replace-section` | `start_s`、`end_s` | `infill_lyrics`（该段的新歌词，最多 5,000 个字符）、`prompt`（上下文歌词）、模型选择、风格字段、`variety`、`max_mode`、`audio_format` | `tracks` |
| `remove-section` | `start_s`、`end_s` | – | `tracks` |
| `crop` | `start_s`、`end_s`：要保留的部分 | – | `tracks` |
| `fade-in`、`fade-out` | `fade_duration`：大于 0 且不超过曲目时长 | `title` | `tracks` |
| `adjust-speed` | `speed`：0.25–4 | `keep_pitch`（默认 `true`）、`title` | `tracks` |
| `stems` | – | `stem_type`（默认 `lead_vocal`；90 多个可选值，如 `drum_kit`、`bass`、`piano`、`808`，完整列表见 API Schema）、`audio_format` | `tracks` |
| `stems-all` | – | `audio_format` | `tracks`，每个分轨一首 |

时间范围以秒为单位，须满足 `0 ≤ start_s < end_s ≤ 曲目时长`。

### 分析与导出

以下动作接受 `task_id`（必填）与 `audio_index`（可选），来源可以是任意曲目。

| 动作 | 除 `task_id` 外必填 | 结果 |
| - | - | - |
| `midi` | – | `midi` |
| `aligned-lyrics` | – | `aligned_lyrics`：带时间轴的歌词 |
| `bpm` | – | `bpm`：`{avg, min, max}` |
| `music-video` | – | `video_url`：MP4 |
| `download` | `formats`：`mp3`、`m4a`、`wav` 中的一个或多个，重复值会被忽略 | `files` |

## 完整示例

每一步都是单独计费的任务。被引用的任务必须先变为 `SUCCEEDED`。

### 生成、续写并拼接为完整歌曲

**第 1 步。** 用 `POST /api/v1/music/generate` 生成：

```json theme={null}
{
  "custom": true,
  "prompt": "[Verse]\n雨夜里霓虹闪烁的街道",
  "title": "Midnight Drive",
  "style": "synthwave, female vocal"
}
```

查询任务，从 `result.tracks` 中选一首，例如 `"index": 2` 的曲目。

**第 2 步。** 用 `POST /api/v1/music/extend` 从 1:30 处续写该曲目：

```json theme={null}
{
  "task_id": "6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11",
  "audio_index": 2,
  "continue_at": 90,
  "prompt": "[Bridge]\n城市在身后渐渐远去"
}
```

**第 3 步。** 用 `POST /api/v1/music/concat` 并传入 `extend` 任务的 `task_id`，拼接为完整歌曲：

```json theme={null}
{
  "task_id": "8a1d2e44-5b6c-4f70-8e91-a2b3c4d5e6f7"
}
```

### 给自己的音频加人声

**第 1 步。** 用 `POST /api/v1/music/upload` 上传音频：

```json theme={null}
{
  "audio_url": "https://example.com/beat.mp3"
}
```

**第 2 步。** 用 `POST /api/v1/music/add-vocals` 并传入 `upload` 任务的 `task_id`：

```json theme={null}
{
  "task_id": "3c9e7f10-2d4b-4a8e-9f61-7b2c1d0e5a94",
  "prompt": "[Verse]\n清晨的光洒在空荡的街",
  "style": "soul, female vocal"
}
```

### 分轨与下载文件

用 `POST /api/v1/music/stems` 从已完成的歌曲中提取一个分轨：

```json theme={null}
{
  "task_id": "6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11",
  "stem_type": "drum_kit"
}
```

改用 `stems-all` 可把曲目拆成全部分轨。需要曲目的 WAV 与 MP3 文件时，调用 `POST /api/v1/music/download`：

```json theme={null}
{
  "task_id": "6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11",
  "formats": ["wav", "mp3"]
}
```

任务完成后，文件按请求顺序列在 `result.files` 中。

## 错误

| HTTP | 含义 |
| - | - |
| 402 | 积分不足 |
| 404 | `music_action_not_found`：未知动作 |
| 422 | `validation_failed`：动作不接受的字段、违反模式规则、长度/范围/枚举不合法，或来源任务不可用（不存在、不属于你、未完成、动作类型不符、序号或时间超出范围） |
| 429 | 触发限流 |
| 503 | `model_unavailable`：Suno 暂不接受新任务 |

错误格式与重试建议见 [错误码](/zh/api-reference/error-codes)。


## OpenAPI

````yaml POST /api/v1/music/{action}
openapi: 3.0.3
info:
  title: Wizzx AI API
  version: 1.2.0
  description: >-
    Wizzx asynchronous image, video, and audio generation API. Model keys are
    placed in the submit URL. Submit returns a Wizzx task_id; poll that ID
    through /api/v1/task/status. Authentication uses a Wizzx API key in the
    Authorization: Bearer <key> header.
  license:
    name: MIT
    url: https://github.com/tonyljx/documentation/blob/main/LICENSE
servers:
  - url: https://api.wizzx.ai
    description: Production API
security: []
tags:
  - name: Discovery
    description: Public model and pricing discovery.
  - name: Credits
    description: Authenticated credit balance.
  - name: Image generation
    description: Asynchronous image tasks.
  - name: Video generation
    description: Asynchronous video tasks.
  - name: Audio generation
    description: Asynchronous music and audio tasks.
  - name: Tasks
    description: Asynchronous task status.
  - name: Legacy models
    description: >-
      Compatibility-only models hidden from /pricing. Do not select these
      automatically.
paths:
  /api/v1/music/{action}:
    post:
      tags:
        - Audio generation
      summary: Submit Suno music action
      description: >-
        Creates one asynchronous paid suno task for the action in the path. Each
        action accepts only its own fields (MusicActionRequest
        x-wizzx-music-actions). Save data.task_id and poll the status endpoint;
        finished tasks return result. Do not automatically retry an ambiguous
        submit.
      operationId: submitMusicAction
      parameters:
        - name: action
          in: path
          required: true
          description: Music action. Unknown actions return 404 music_action_not_found.
          schema:
            type: string
            enum:
              - generate
              - inspo
              - sounds
              - lyrics
              - upsample-tags
              - upload
              - upload-cover
              - upload-extend
              - create-model
              - create-voice
              - extend
              - concat
              - cover
              - remaster
              - add-vocals
              - add-instrumental
              - add-stem
              - mashup
              - sample
              - persona
              - replace-section
              - remove-section
              - crop
              - fade-in
              - fade-out
              - adjust-speed
              - stems
              - stems-all
              - midi
              - aligned-lyrics
              - bpm
              - music-video
              - download
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MusicActionRequest'
            examples:
              generate:
                summary: generate
                value:
                  custom: true
                  prompt: |-
                    [Verse]
                    Neon-lit streets on a rainy night
                  title: Midnight Drive
                  style: synthwave, female vocal
              inspo:
                summary: inspo
                value:
                  audio_urls:
                    - https://example.com/reference.mp3
                  style: dream pop
              sounds:
                summary: sounds
                value:
                  prompt: Punchy lo-fi drum loop
                  sound_type: loop
                  bpm: 90
                  key: Am
              lyrics:
                summary: lyrics
                value:
                  prompt: A road trip song about leaving a small town
              upsample-tags:
                summary: upsample-tags
                value:
                  style: lofi, rainy night
              upload:
                summary: upload
                value:
                  audio_url: https://example.com/beat.mp3
              upload-cover:
                summary: upload-cover
                value:
                  audio_url: https://example.com/demo.mp3
                  custom: false
                  gpt_description: Turn this demo into an upbeat acoustic pop song
              upload-extend:
                summary: upload-extend
                value:
                  audio_url: https://example.com/intro.mp3
                  continue_at: 30
                  prompt: |-
                    [Chorus]
                    We keep on driving
              create-model:
                summary: create-model
                value:
                  name: My band sound
                  audio_urls:
                    - https://example.com/song-1.mp3
                    - https://example.com/song-2.mp3
                    - https://example.com/song-3.mp3
                    - https://example.com/song-4.mp3
                    - https://example.com/song-5.mp3
                    - https://example.com/song-6.mp3
              create-voice:
                summary: create-voice
                value:
                  audio_url: https://example.com/voice.wav
              extend:
                summary: extend
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  audio_index: 2
                  continue_at: 90
                  prompt: |-
                    [Bridge]
                    The city fades behind us
              concat:
                summary: concat
                value:
                  task_id: 8a1d2e44-5b6c-4f70-8e91-a2b3c4d5e6f7
              cover:
                summary: cover
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  style: jazz, upright bass, brushed drums
              remaster:
                summary: remaster
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  variation_category: subtle
              add-vocals:
                summary: add-vocals
                value:
                  task_id: 3c9e7f10-2d4b-4a8e-9f61-7b2c1d0e5a94
                  prompt: |-
                    [Verse]
                    Morning light on an empty street
                  style: soul, female vocal
              add-instrumental:
                summary: add-instrumental
                value:
                  task_id: 3c9e7f10-2d4b-4a8e-9f61-7b2c1d0e5a94
                  style: acoustic guitar, warm pads
              add-stem:
                summary: add-stem
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  style: add a string section
              mashup:
                summary: mashup
                value:
                  task_ids:
                    - 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                    - 9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
                  audio_indexes:
                    - 1
                    - 2
                  custom: false
                  gpt_description: Blend both songs into an energetic dance track
              sample:
                summary: sample
                value:
                  task_id: 3c9e7f10-2d4b-4a8e-9f61-7b2c1d0e5a94
                  start_s: 4
                  end_s: 12
                  custom: true
                  instrumental: true
                  style: boom bap, vinyl crackle
              persona:
                summary: persona
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  name: Night singer
                  start_s: 20
                  end_s: 45
              replace-section:
                summary: replace-section
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  start_s: 30
                  end_s: 45
                  infill_lyrics: We ride until the morning comes
              remove-section:
                summary: remove-section
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  start_s: 60
                  end_s: 75
              crop:
                summary: crop
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  start_s: 0
                  end_s: 30
              fade-in:
                summary: fade-in
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  fade_duration: 3
              fade-out:
                summary: fade-out
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  fade_duration: 5
              adjust-speed:
                summary: adjust-speed
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  speed: 1.25
              stems:
                summary: stems
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  stem_type: drum_kit
              stems-all:
                summary: stems-all
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
              midi:
                summary: midi
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
              aligned-lyrics:
                summary: aligned-lyrics
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
              bpm:
                summary: bpm
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
              music-video:
                summary: music-video
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
              download:
                summary: download
                value:
                  task_id: 6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11
                  formats:
                    - wav
                    - mp3
      responses:
        '200':
          description: Task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskSubmitResponse'
        '400':
          description: Malformed JSON or binding validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown music action (music_action_not_found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body exceeds the configured limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Field not accepted by the action, mode or range violation, or
            unusable source task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Retry-After:
              description: Retry delay in seconds.
              schema:
                type: integer
                minimum: 0
        '500':
          description: Internal or upstream submission error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service or model temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    MusicActionRequest:
      type: object
      additionalProperties: false
      description: >-
        Request body for POST /api/v1/music/{action}. Each action accepts only
        its own fields, listed per action in x-wizzx-music-actions; sending a
        field the action does not accept returns 422. Earlier tasks are
        referenced by Wizzx task_id only and must be your own SUCCEEDED suno
        tasks.
      properties:
        prompt:
          type: string
          maxLength: 5000
          description: >-
            Lyrics in custom mode (at most 5000 characters). A description (at
            most 3000 characters) for generate inspiration mode, the lyrics
            topic, and the sounds description.
        gpt_description:
          type: string
          maxLength: 3000
          description: >-
            Song description for inspiration mode (custom=false) on actions
            other than generate.
        custom:
          type: boolean
          description: >-
            Custom (lyrics) mode. generate defaults to false; extend defaults to
            true; upload-cover requires it; cover, add-vocals, add-instrumental,
            add-stem, mashup, and sample infer it when omitted (prompt, style,
            or title means true; gpt_description means false).
        instrumental:
          type: boolean
          default: false
          description: No vocals. Cannot be combined with vocal_gender.
        version:
          type: string
          enum:
            - v6
            - v6-wild
            - v6-mini
          default: v6
          description: >-
            Case-insensitive. All versions cost the same. Cannot be combined
            with custom_model_task_id.
        custom_model_task_id:
          type: string
          format: uuid
          description: >-
            task_id of your SUCCEEDED create-model task. Replaces version;
            cannot be combined with version or persona_task_id.
        persona_task_id:
          type: string
          format: uuid
          description: >-
            task_id of your SUCCEEDED persona or create-voice task. Custom mode
            only.
        title:
          type: string
          maxLength: 80
          description: Custom mode only on actions with a mode switch.
        style:
          type: string
          maxLength: 1000
          description: >-
            Style tags. Custom mode only on actions with a mode switch. Required
            by upsample-tags.
        negative_tags:
          type: string
          maxLength: 1000
          description: Styles to avoid. Custom mode only on actions with a mode switch.
        style_weight:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How strongly to follow style, 0-1. Custom mode only on actions other
            than generate.
        weirdness:
          type: number
          minimum: 0
          maximum: 1
          description: How experimental the result is, 0-1.
        audio_weight:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How closely to follow the source audio, 0-1. Custom mode only on
            actions other than generate.
        vocal_gender:
          type: string
          enum:
            - Male
            - Female
          description: >-
            Case-insensitive; m and f are accepted. Cannot be combined with
            instrumental=true.
        auto_lyrics:
          type: boolean
          default: false
          description: Custom mode only.
        variety:
          type: string
          enum:
            - 'off'
            - normal
            - high
            - extra
            - max
        max_mode:
          type: boolean
          default: false
          description: >-
            Higher quality at double the price. Requires custom mode on actions
            with a mode switch.
        audio_format:
          type: string
          enum:
            - mp3
            - m4a
            - wav
        duration:
          type: integer
          minimum: 10
          maximum: 360
          description: >-
            Target length in seconds; actual length may differ. Custom mode only
            on actions with a mode switch. Does not change the price.
        task_id:
          type: string
          format: uuid
          description: 'Source task: one of your SUCCEEDED suno tasks that produced tracks.'
        audio_index:
          type: integer
          minimum: 1
          maximum: 20
          default: 1
          description: 1-based result.tracks[].index of the source task.
        task_ids:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: string
            format: uuid
          description: 'mashup: exactly two source tasks.'
        audio_indexes:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: integer
            minimum: 1
            maximum: 20
          default:
            - 1
            - 1
          description: 'mashup: track index for each task_ids entry.'
        audio_url:
          type: string
          format: uri
          pattern: ^https?://
          description: Publicly reachable HTTP(S) audio URL, at most 2048 characters.
          maxLength: 2048
        audio_urls:
          type: array
          minItems: 1
          maxItems: 24
          items:
            type: string
            format: uri
            pattern: ^https?://
            description: Publicly reachable HTTP(S) audio URL, at most 2048 characters.
            maxLength: 2048
          description: >-
            inspo: 1-4 reference audio URLs. create-model: 6-24 training audio
            URLs.
        continue_at:
          type: number
          minimum: 1
          description: >-
            Seconds into the source audio where the continuation starts. For
            extend it must be less than the source track duration.
        start_s:
          type: number
          minimum: 0
          description: Section start in seconds.
        end_s:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Section end in seconds. Greater than start_s and not beyond the
            source track duration.
        fade_duration:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: Fade length in seconds; not longer than the source track.
        speed:
          type: number
          minimum: 0.25
          maximum: 4
        keep_pitch:
          type: boolean
          default: true
        stem_type:
          type: string
          enum:
            - lead_vocal
            - drum_kit
            - bass
            - backing_vocals
            - piano
            - electric_guitar
            - percussion
            - string_section
            - synth
            - acoustic_guitar
            - sound_effects
            - synth_pad
            - synth_bass
            - guitar
            - brass_section
            - organ
            - electronic_drum_kit
            - lead_electric_guitar
            - synth_keys
            - rhythm_electric_guitar
            - electric_piano
            - upright_bass
            - keyboards
            - distorted_electric_guitar
            - kick
            - snare
            - risers
            - synth_strings
            - synth_lead
            - woodwinds
            - flute
            - harp
            - tambourine
            - trumpet
            - arpeggiator
            - accordion
            - fiddle
            - pedal_steel_guitar
            - synth_voice
            - violin
            - digital_piano
            - synth_brass
            - mandolin
            - choir
            - banjo
            - bells
            - clarinet
            - tenor_saxophone
            - trombone
            - shaker
            - french_horn
            - glockenspiel
            - electric_bass
            - cello
            - timpani
            - harmonica
            - marimba
            - vibraphone
            - lap_steel_guitar
            - saxophone
            - orchestra
            - horns
            - cymbals
            - hand_clap
            - oboe
            - celesta
            - congas
            - drone
            - alto_saxophone
            - double_bass
            - ukulele
            - harpsichord
            - baritone_saxophone
            - xylophone
            - tuba
            - bass_guitar
            - whistle
            - lead_guitar
            - rhodes
            - '808'
            - bongos
            - bassoon
            - cowbell
            - viola
            - sitar
            - steel_drums
            - piccolo
            - theremin
            - bagpipes
            - hi_hat
            - music_box
            - melodica
            - tabla
            - koto
            - djembe
            - taiko
            - didgeridoo
          default: lead_vocal
          description: Case-insensitive.
        infill_lyrics:
          type: string
          maxLength: 5000
          description: 'replace-section: lyrics for the replaced section.'
        variation_category:
          type: string
          enum:
            - subtle
            - normal
            - high
        sound_type:
          type: string
          enum:
            - one-shot
            - loop
        bpm:
          type: integer
          minimum: 1
          maximum: 300
        key:
          type: string
          enum:
            - C
            - Cm
            - C#
            - C#m
            - D
            - Dm
            - D#
            - D#m
            - E
            - Em
            - F
            - Fm
            - F#
            - F#m
            - G
            - Gm
            - G#
            - G#m
            - A
            - Am
            - A#
            - A#m
            - B
            - Bm
          description: Sharp notation; append m for minor.
        lyrics_model:
          type: string
          enum:
            - classic
            - remi
        name:
          type: string
          maxLength: 80
          description: create-model or persona name.
        description:
          type: string
          maxLength: 1000
          description: persona description.
        formats:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - mp3
              - m4a
              - wav
          description: Duplicates are ignored.
      x-wizzx-music-actions:
        generate:
          group: Creation
          required:
            - prompt
          accepted:
            - prompt
            - custom
            - instrumental
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
            - duration
          source: none
          result: tracks
        inspo:
          group: Creation
          required:
            - audio_urls
          accepted:
            - audio_urls
            - prompt
            - version
            - custom_model_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
          source: none
          result: tracks
        sounds:
          group: Creation
          required:
            - prompt
          accepted:
            - prompt
            - version
            - sound_type
            - bpm
            - key
            - audio_format
          source: none
          result: tracks
        lyrics:
          group: Creation
          required:
            - prompt
          accepted:
            - prompt
            - lyrics_model
          source: none
          result: lyrics
        upsample-tags:
          group: Creation
          required:
            - style
          accepted:
            - style
          source: none
          result: style
        upload:
          group: Creation
          required:
            - audio_url
          accepted:
            - audio_url
          source: none
          result: tracks
        upload-cover:
          group: Creation
          required:
            - audio_url
            - custom
          accepted:
            - audio_url
            - custom
            - prompt
            - gpt_description
            - instrumental
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
            - duration
          source: none
          result: tracks
        upload-extend:
          group: Creation
          required:
            - audio_url
            - continue_at
          accepted:
            - audio_url
            - continue_at
            - prompt
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
            - duration
          source: none
          result: tracks
        create-model:
          group: Creation
          required:
            - name
            - audio_urls
          accepted:
            - name
            - audio_urls
          source: none
          result: model_id
        create-voice:
          group: Creation
          required:
            - audio_url
          accepted:
            - audio_url
          source: none
          result: persona_id
        extend:
          group: From an existing track
          required:
            - task_id
            - continue_at
          accepted:
            - task_id
            - audio_index
            - continue_at
            - custom
            - prompt
            - gpt_description
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
            - duration
          source: any track
          result: tracks
        concat:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - audio_format
          source: extend task
          result: tracks
        cover:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - custom
            - prompt
            - gpt_description
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - max_mode
            - duration
          source: any track
          result: tracks
        remaster:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - variation_category
            - audio_format
          source: any track
          result: tracks
        add-vocals:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - custom
            - prompt
            - gpt_description
            - version
            - custom_model_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - max_mode
          source: upload task
          result: tracks
        add-instrumental:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - custom
            - prompt
            - gpt_description
            - version
            - custom_model_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - max_mode
          source: upload task
          result: tracks
        add-stem:
          group: From an existing track
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - custom
            - prompt
            - gpt_description
            - version
            - custom_model_task_id
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - variety
            - audio_format
            - max_mode
          source: any track
          result: tracks
        mashup:
          group: From an existing track
          required:
            - task_ids
          accepted:
            - task_ids
            - audio_indexes
            - custom
            - prompt
            - gpt_description
            - instrumental
            - version
            - custom_model_task_id
            - persona_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
          source: two tracks
          result: tracks
        sample:
          group: From an existing track
          required:
            - task_id
            - start_s
            - end_s
          accepted:
            - task_id
            - audio_index
            - start_s
            - end_s
            - custom
            - prompt
            - gpt_description
            - instrumental
            - version
            - custom_model_task_id
            - vocal_gender
            - variety
            - audio_format
            - style_weight
            - weirdness
            - audio_weight
            - title
            - style
            - negative_tags
            - auto_lyrics
            - max_mode
          source: upload task
          result: tracks
        persona:
          group: From an existing track
          required:
            - task_id
            - name
          accepted:
            - task_id
            - audio_index
            - name
            - description
            - style
            - start_s
            - end_s
          source: any track
          result: persona_id
        replace-section:
          group: Editing
          required:
            - task_id
            - start_s
            - end_s
          accepted:
            - task_id
            - audio_index
            - start_s
            - end_s
            - infill_lyrics
            - prompt
            - version
            - custom_model_task_id
            - title
            - style
            - negative_tags
            - variety
            - max_mode
            - audio_format
          source: any track
          result: tracks
        remove-section:
          group: Editing
          required:
            - task_id
            - start_s
            - end_s
          accepted:
            - task_id
            - audio_index
            - start_s
            - end_s
          source: any track
          result: tracks
        crop:
          group: Editing
          required:
            - task_id
            - start_s
            - end_s
          accepted:
            - task_id
            - audio_index
            - start_s
            - end_s
          source: any track
          result: tracks
        fade-in:
          group: Editing
          required:
            - task_id
            - fade_duration
          accepted:
            - task_id
            - audio_index
            - fade_duration
            - title
          source: any track
          result: tracks
        fade-out:
          group: Editing
          required:
            - task_id
            - fade_duration
          accepted:
            - task_id
            - audio_index
            - fade_duration
            - title
          source: any track
          result: tracks
        adjust-speed:
          group: Editing
          required:
            - task_id
            - speed
          accepted:
            - task_id
            - audio_index
            - speed
            - keep_pitch
            - title
          source: any track
          result: tracks
        stems:
          group: Editing
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - stem_type
            - audio_format
          source: any track
          result: tracks
        stems-all:
          group: Editing
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
            - audio_format
          source: any track
          result: tracks
        midi:
          group: Analysis & export
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
          source: any track
          result: midi
        aligned-lyrics:
          group: Analysis & export
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
          source: any track
          result: aligned_lyrics
        bpm:
          group: Analysis & export
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
          source: any track
          result: bpm
        music-video:
          group: Analysis & export
          required:
            - task_id
          accepted:
            - task_id
            - audio_index
          source: any track
          result: video_url
        download:
          group: Analysis & export
          required:
            - task_id
            - formats
          accepted:
            - task_id
            - audio_index
            - formats
          source: any track
          result: files
    TaskSubmitResponse:
      type: object
      required:
        - code
        - message
        - data
        - request_id
      properties:
        code:
          type: integer
          enum:
            - 0
        message:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/TaskSubmitData'
        request_id:
          type: string
          format: uuid
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
        request_id:
          type: string
          format: uuid
        retry_after:
          type: integer
          format: int64
          minimum: 0
          description: Retry delay in seconds. Present for rate-limit errors.
    TaskSubmitData:
      type: object
      required:
        - task_id
        - model_key
        - credits_deducted
      properties:
        task_id:
          type: string
          format: uuid
          description: Wizzx task ID used for status polling.
        model_key:
          type: string
        action:
          type: string
          description: Music action. Returned only by POST /api/v1/music/{action}.
        credits_deducted:
          type: integer
          minimum: 0
          description: Credits reserved when the task is accepted.
        provider_task_id:
          type: string
          description: Diagnostic field returned only when debug=1.
        provider_key:
          type: string
          description: Diagnostic field returned only when debug=1.
    ErrorDetail:
      type: object
      required:
        - message
        - type
        - param
        - code
      properties:
        message:
          type: string
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - insufficient_quota
            - permission_denied
            - not_found_error
            - conflict_error
            - unprocessable_entity_error
            - rate_limit_error
            - server_error
            - service_unavailable
        param:
          type: string
          nullable: true
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Wizzx API key. This is not a JWT.

````

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