> ## 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.

# Submit music action

> POST a Suno music action to create, extend, edit, separate, analyze, or export tracks

## Overview

`POST /api/v1/music/{action}` is the main entry point for [Suno](/models/suno) music. The path names one of 33 actions. Every action creates one asynchronous task of the `suno` model: save `data.task_id`, then poll [`POST /api/v1/task/status`](/api-reference/endpoint/task-status) until the task finishes. Each call is billed once; see [credits per action](/models/suno#pricing).

`POST /api/v1/task/submit/suno` still works and is identical to the `generate` action.

```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]\nNeon-lit streets on a rainy night",
    "title": "Midnight Drive",
    "style": "synthwave, female vocal"
  }'
```

The response uses the usual submit envelope and adds `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"
}
```

## Rules for every action

* **Strict fields.** Each action accepts only the fields listed for it below. Sending a music field that the action does not accept returns HTTP 422 `validation_failed`, for example `music action bpm does not accept version`. Omit fields you do not need.
* An unknown action returns HTTP 404 `music_action_not_found`.
* Text limits count Unicode characters. Audio URLs must be public HTTP(S) URLs of at most 2,048 characters.
* Earlier tasks are referenced only by their Wizzx `task_id`. See [Referencing earlier tasks](#referencing-earlier-tasks).
* Music actions share the submit rate limit. Validation and source-task errors are returned before any credits are reserved.

## Shared fields

These fields mean the same thing in every action that accepts them.

| Field | Type | Rules |
| - | - | - |
| `prompt` | string | Lyrics in custom mode, at most 5,000 characters. A description of at most 3,000 characters for `generate` inspiration mode, the `lyrics` topic, and the `sounds` description |
| `gpt_description` | string | Song description for inspiration mode (`custom: false`) on actions other than `generate`, at most 3,000 characters |
| `custom` | boolean | Custom (lyrics) mode switch. See [Custom and inspiration mode](#custom-and-inspiration-mode) |
| `instrumental` | boolean | `true` for no vocals. Cannot be combined with `vocal_gender` |
| `version` | string | `v6` (default), `v6-wild`, or `v6-mini`, case-insensitive, same price |
| `custom_model_task_id` | string | `task_id` of your finished `create-model` task. Use it instead of `version`; cannot be combined with `version` or `persona_task_id` |
| `persona_task_id` | string | `task_id` of your finished `persona` or `create-voice` task. Custom mode only |
| `title` | string | At most 80 characters |
| `style` | string | Style tags, at most 1,000 characters |
| `negative_tags` | string | Styles to avoid, at most 1,000 characters |
| `style_weight`, `weirdness`, `audio_weight` | number | 0–1; `0` is a valid value |
| `vocal_gender` | string | `Male` or `Female` (`m` and `f` are accepted). Not allowed with `instrumental: true` |
| `auto_lyrics` | boolean | Custom mode only |
| `variety` | string | `off`, `normal`, `high`, `extra`, or `max` |
| `max_mode` | boolean | Higher quality at double the price. Requires custom mode on actions that have a mode switch |
| `audio_format` | string | `mp3`, `m4a`, or `wav` |
| `duration` | integer | Target length of 10–360 seconds; the actual length may differ. Does not change the price |
| `task_id` | string | Source task. See [Referencing earlier tasks](#referencing-earlier-tasks) |
| `audio_index` | integer | 1–20, default `1`: the `result.tracks[].index` of the source track |

The action tables below use these shorthands:

* **Model choice**: `version` or `custom_model_task_id`
* **Style fields**: `title`, `style`, `negative_tags`
* **Weights**: `style_weight`, `weirdness`, `audio_weight`
* **Mode fields**: `custom`, `prompt`, `gpt_description`

## Custom and inspiration mode

Some actions switch between custom mode, where you write lyrics and style, and inspiration mode, where Suno works from a description.

| Action | How the mode is chosen |
| - | - |
| `generate` | `custom` defaults to `false`. Inspiration mode: `prompt` is a required song description. Custom mode: `prompt` holds lyrics and is required unless `instrumental` is `true`; a custom instrumental needs `prompt` or `style` |
| `upload-cover` | `custom` is **required**. `false` needs `gpt_description`; `true` needs `prompt` unless `instrumental` is `true` |
| `extend` | `custom` defaults to `true`. `false` needs `gpt_description` |
| `cover`, `add-vocals`, `add-instrumental`, `add-stem`, `mashup`, `sample` | When `custom` is omitted it is inferred: `prompt` means custom; otherwise `gpt_description` means inspiration; otherwise `style` or `title` means custom; with none of them the request returns 422. `mashup` and `sample` in custom mode need `prompt` unless `instrumental` is `true` |
| `upload-extend` | Always custom mode; there is no `custom` field |

In inspiration mode, `generate` rejects `title`, `style`, `negative_tags`, `auto_lyrics`, `persona_task_id`, `duration`, and `max_mode`. The other actions reject `prompt`, `title`, `style`, `negative_tags`, `auto_lyrics`, `persona_task_id`, `duration`, `max_mode`, `style_weight`, and `audio_weight`. In custom mode, `gpt_description` is rejected.

## Referencing earlier tasks

Many actions build on a track you already generated:

* `task_id` + `audio_index` select one track. `audio_index` is the 1-based `index` of the track in the source task's `result.tracks` and defaults to `1`.
* `mashup` uses `task_ids` (exactly two tasks) and `audio_indexes` (two entries, default `[1, 1]`) instead.
* `custom_model_task_id` must point to a finished `create-model` task, and `persona_task_id` to a finished `persona` or `create-voice` task.

Every referenced task must be your own `suno` task with status `SUCCEEDED`. Only actions that produce tracks can be a track source: `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`, and `sample`. Lyrics, style, analysis, persona, model, voice, video, and download results cannot.

Some actions need a specific kind of source:

| Action | Source task must be |
| - | - |
| `add-vocals`, `add-instrumental`, `sample` | An `upload` task |
| `concat` | An `extend` task |

Before charging, the gateway also checks that `audio_index` exists in the source task and that `continue_at`, `end_s`, and `fade_duration` fit the source track's duration. Any failed check returns HTTP 422 and no credits are reserved.

<Note>
  Tasks that finished before October 15, 2026 have no `result` object. They can still be used as sources, but the track index and times cannot be checked in advance; an out-of-range value then fails the task and its credits are refunded.
</Note>

## Actions

All actions return their output in the task status [`result`](/api-reference/endpoint/task-status#music-results) object.

### Creation

| Action | Required | Optional | Result |
| - | - | - | - |
| `generate` | `prompt`, except for a custom-mode instrumental ([modes](#custom-and-inspiration-mode)) | `custom`, `instrumental`, model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format`, `duration` | `tracks`, usually two |
| `inspo` | `audio_urls`: 1–4 public reference audio URLs | `prompt` (lyrics), model choice, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format` | `tracks` |
| `sounds` | `prompt`: sound description | `version`, `sound_type` (`one-shot` or `loop`), `bpm` (integer 1–300), `key` (`C` to `B` in sharp notation such as `F#`, add `m` for minor such as `C#m`), `audio_format` | `tracks` |
| `lyrics` | `prompt`: topic | `lyrics_model` (`classic` or `remi`) | `lyrics` |
| `upsample-tags` | `style` | – | `style` (enhanced) |
| `upload` | `audio_url` | – | `tracks`; a track may have no `audio_url`. Use the task as the source for `add-vocals`, `add-instrumental`, and `sample` |
| `upload-cover` | `audio_url` (shorter than 8 minutes), `custom` | mode fields, `instrumental`, model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format`, `duration` | `tracks` |
| `upload-extend` | `audio_url`, `continue_at` (at least 1 second) | `prompt` (lyrics), model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format`, `duration` | `tracks` |
| `create-model` | `name` (at most 80 characters), `audio_urls`: 6–24 public audio URLs | – | `model_id`. Use this task's `task_id` as `custom_model_task_id`. Can take about 20 minutes |
| `create-voice` | `audio_url` (MP3 or WAV): a clean vocal recording without music | – | `persona_id`; use this task's `task_id` as `persona_task_id` |

### From an existing track

These actions take `task_id` (required) and `audio_index` (optional) unless noted.

| Action | Required besides `task_id` | Optional | Source | Result |
| - | - | - | - | - |
| `extend` | `continue_at`: at least 1 second and less than the track duration | mode fields (`custom` defaults to `true`), model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format`, `duration` | Any track | `tracks` |
| `concat` | – | `audio_format` | `extend` task | `tracks`: the full joined song |
| `cover` | Mode ([inferred](#custom-and-inspiration-mode)) | mode fields, model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `variety`, `max_mode`, `audio_format`, `duration` | Any track | `tracks` |
| `remaster` | – | `variation_category` (`subtle`, `normal`, or `high`), `audio_format` | Any track | `tracks` |
| `add-vocals` | Mode ([inferred](#custom-and-inspiration-mode)) | mode fields, model choice, style fields, weights, `vocal_gender`, `variety`, `max_mode`, `audio_format` | `upload` task | `tracks` |
| `add-instrumental` | Mode ([inferred](#custom-and-inspiration-mode)) | Same as `add-vocals` | `upload` task | `tracks` |
| `add-stem` | Mode ([inferred](#custom-and-inspiration-mode)) | mode fields, model choice, style fields, weights, `variety`, `max_mode`, `audio_format` | Any track | `tracks` |
| `mashup` | `task_ids`: exactly two tasks, instead of `task_id`; mode ([inferred](#custom-and-inspiration-mode)) | `audio_indexes` (two entries, default `[1, 1]`), mode fields, `instrumental`, model choice, `persona_task_id`, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format` | Two tracks | `tracks` |
| `sample` | `start_s`, `end_s`; mode ([inferred](#custom-and-inspiration-mode)) | mode fields, `instrumental`, model choice, style fields, weights, `vocal_gender`, `auto_lyrics`, `variety`, `max_mode`, `audio_format` | `upload` task | `tracks` |
| `persona` | `name` (at most 80 characters) | `description` (at most 1,000 characters), `style`, `start_s` / `end_s` (vocal clip) | Any track | `persona_id`. Use this task's `task_id` as `persona_task_id` |

### Editing

All editing actions take `task_id` (required) and `audio_index` (optional) and accept any track as the source.

| Action | Required besides `task_id` | Optional | Result |
| - | - | - | - |
| `replace-section` | `start_s`, `end_s` | `infill_lyrics` (new lyrics for the section, at most 5,000 characters), `prompt` (surrounding lyrics for context), model choice, style fields, `variety`, `max_mode`, `audio_format` | `tracks` |
| `remove-section` | `start_s`, `end_s` | – | `tracks` |
| `crop` | `start_s`, `end_s`: the part to keep | – | `tracks` |
| `fade-in`, `fade-out` | `fade_duration`: greater than 0 and not longer than the track | `title` | `tracks` |
| `adjust-speed` | `speed`: 0.25–4 | `keep_pitch` (default `true`), `title` | `tracks` |
| `stems` | – | `stem_type` (default `lead_vocal`; more than 90 values such as `drum_kit`, `bass`, `piano`, `808`; see the API schema for the full list), `audio_format` | `tracks` |
| `stems-all` | – | `audio_format` | `tracks`, one per stem |

Time ranges are in seconds and must satisfy `0 ≤ start_s < end_s ≤ track duration`.

### Analysis and export

These actions take `task_id` (required) and `audio_index` (optional) and accept any track as the source.

| Action | Required besides `task_id` | Result |
| - | - | - |
| `midi` | – | `midi` |
| `aligned-lyrics` | – | `aligned_lyrics`: lyrics with timing |
| `bpm` | – | `bpm`: `{avg, min, max}` |
| `music-video` | – | `video_url`: MP4 |
| `download` | `formats`: one or more of `mp3`, `m4a`, `wav`; duplicates are ignored | `files` |

## Worked examples

Each step is a separate paid task. Wait until a task is `SUCCEEDED` before you reference it.

### Generate, extend, and join into one song

**Step 1.** Generate with `POST /api/v1/music/generate`:

```json theme={null}
{
  "custom": true,
  "prompt": "[Verse]\nNeon-lit streets on a rainy night",
  "title": "Midnight Drive",
  "style": "synthwave, female vocal"
}
```

Poll the task and pick a track from `result.tracks`, for example the one with `"index": 2`.

**Step 2.** Extend that track from 1:30 with `POST /api/v1/music/extend`:

```json theme={null}
{
  "task_id": "6f0c1c52-2a4b-4d53-9a5e-3c0f2f7d9e11",
  "audio_index": 2,
  "continue_at": 90,
  "prompt": "[Bridge]\nThe city fades behind us"
}
```

**Step 3.** Join the continuation into a full song with `POST /api/v1/music/concat`, using the `task_id` of the `extend` task:

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

### Add vocals to your own audio

**Step 1.** Upload the audio with `POST /api/v1/music/upload`:

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

**Step 2.** Add vocals with `POST /api/v1/music/add-vocals`, using the `task_id` of the `upload` task:

```json theme={null}
{
  "task_id": "3c9e7f10-2d4b-4a8e-9f61-7b2c1d0e5a94",
  "prompt": "[Verse]\nMorning light on an empty street",
  "style": "soul, female vocal"
}
```

### Separate stems and download files

Extract one stem from a finished song with `POST /api/v1/music/stems`:

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

Use `stems-all` instead to split the track into every stem. To get WAV and MP3 files of a track, call `POST /api/v1/music/download`:

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

The finished task lists the files in `result.files`, in request order.

## Errors

| HTTP | Meaning |
| - | - |
| 402 | Insufficient credits |
| 404 | `music_action_not_found`: unknown action |
| 422 | `validation_failed`: a field the action does not accept, a mode rule, a length, range, or enum violation, or an unusable source task (not found, not yours, not finished, wrong action, or index or time out of range) |
| 429 | Rate limited |
| 503 | `model_unavailable`: Suno is not accepting new tasks |

See [Error codes](/api-reference/error-codes) for the error format and retry guidance.


## 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.