API REFERENCE

Generate Music

On this page

POST/api/music

Start a song generation with MiniMax Music 3. Generation runs in the background and takes roughly one to two minutes, so this returns 202 immediately with a pending generation. Poll Get Music Generation until status is completed or failed; audio_url is populated on completion. Credits are checked before the model is called and deducted only when a generation completes, so a failed generation is never charged.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/music' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Genre: acoustic pop. BPM: 96. Key: C major. Warm and intimate, building gently into the chorus.",
  "lyrics": "[verse]\nMorning light filtering through the pine\n[chorus]\nSoftly the world begins to breathe"
}'

Request body required

application/json

promptstringrequired

Music description: style, mood, vocals, instrumentation and arrangement.

lyricsstringrequired

The lyrics to sing. Structure tags such as [intro], [verse], [chorus] and [outro] must each be on their own line; text on the same line as a leading tag is dropped by the model.

durationnumber

Upper bound on the generated audio length in seconds. The model may stop earlier; the actual length comes back as duration_seconds.

Default: 60

minimum: 10 · maximum: 300

seedinteger

Seed for reproducibility. Omit for a random seed.

num_inference_stepsinteger

Flow-matching steps per denoising chunk. More steps improve quality at the cost of speed.

Default: 30

minimum: 1 · maximum: 100

guidance_scalenumber

Classifier-free guidance scale of the flow-matching stage.

Default: 1.7

minimum: 0 · maximum: 20

account_idstring

Optional. Generate on behalf of another account you can access (self, shared organization, or admin). Defaults to the calling account. Organizations are accounts, so this is also how an organization generation is scoped: send the organization's account id.

format: uuid

Responses

202Generation accepted and queued.

Locationresponse header

URL of the created generation.

application/json

statusstring · enum

Status of the request

Values: "success"

generationobject

One music generation.

Properties

idstring

The generation's id. Poll Get Music Generation with this.

format: uuid

statusstring · enum

Lifecycle phase. pending until the workflow picks it up, processing while fal is rendering, then completed or failed.

Values: "pending", "processing", "completed", "failed"

promptstring

The music description the song was generated from.

lyricsstring

The lyrics the song was generated from.

modelstring

The generating model.

duration_secondsnumber | null

Actual length of the generated audio. Null until completed; may be shorter than requested.

audio_urlstring | null

Playable audio URL. Null until the generation completes.

error_messagestring | null

Why the generation failed. Null unless status is failed.

created_atstring

When the generation was created.

format: date-time

updated_atstring

When the generation last changed.

format: date-time

400Validation failed. missing_fields names the first offending field.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

401Unauthorized. Provide exactly one of x-api-key or Authorization: Bearer.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

402Insufficient credits. No generation is created and the model is not called.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

403Access denied to the specified account_id or organization_id.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

500Internal server error.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "summary": "Generate music",
  "description": "Start a song generation with MiniMax Music 3. Generation runs in the background and takes roughly one to two minutes, so this returns **202** immediately with a `pending` generation. Poll [Get Music Generation](/api-reference/music/get) until `status` is `completed` or `failed`; `audio_url` is populated on completion. Credits are checked before the model is called and deducted only when a generation completes, so a failed generation is never charged.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicGenerationRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Generation accepted and queued.",
      "headers": {
        "Location": {
          "schema": {
            "type": "string"
          },
          "description": "URL of the created generation."
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationCreateResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed. `missing_fields` names the first offending field.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized. Provide exactly one of `x-api-key` or `Authorization: Bearer`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits. No generation is created and the model is not called.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the specified `account_id` or `organization_id`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    }
  }
}