RecoupGet a free auditFree audit

API REFERENCE

Compose music

On this page
POST/api/music/compose

Generate a song from a text prompt or a composition plan. The prompt can describe mood, genre, instruments, lyrics, and structure. Alternatively, pass a full composition_plan for fine-grained control over sections, styles, and lyrics. Returns binary audio in the requested format (default MP3).

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/music/compose' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string",
  "composition_plan": {},
  "duration": 30,
  "output_format": "mp3_44100_192",
  "sign_with_c2pa": false
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/music/compose' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string",
  "composition_plan": {},
  "duration": 30,
  "output_format": "mp3_44100_192",
  "sign_with_c2pa": false
}'

Request body required

Music composition parameters

application/json

promptstring

Text prompt describing the desired song — mood, genre, instruments, lyrics, structure.

composition_planobject

Full composition plan for fine-grained control over sections, styles, and lyrics. Use POST /api/music/plan to generate one.

durationnumber

Desired duration in seconds.

Default: 30

output_formatstring

Audio output format (e.g. mp3_44100_192).

Default: "mp3_44100_192"

sign_with_c2paboolean

Sign the output with C2PA content credentials.

Default: false

Responses

200Audio generated successfully
song-idresponse header

Unique identifier for the generated song

audio/mpeg

string

400Validation failed — invalid or missing request body fields

application/json

errorstringrequired

Error message describing what went wrong.

401Unauthorized — invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong.

500Internal server error

application/json

errorstringrequired

Error message describing what went wrong.

Full specification

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

Download content.json
View operation source
json
{
  "description": "Generate a song from a text prompt or a composition plan. The prompt can describe mood, genre, instruments, lyrics, and structure. Alternatively, pass a full composition_plan for fine-grained control over sections, styles, and lyrics. Returns binary audio in the requested format (default MP3).",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Music composition parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicComposeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Audio generated successfully",
      "headers": {
        "song-id": {
          "schema": {
            "type": "string"
          },
          "description": "Unique identifier for the generated song"
        }
      },
      "content": {
        "audio/mpeg": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed — invalid or missing request body fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicErrorResponse"
          }
        }
      }
    }
  }
}