RecoupGet a free auditFree audit

API REFERENCE

Compose Music with Metadata

On this page
POST/api/music/compose/detailed

Generate a song with metadata and optional word-level timestamps. Returns a multipart/mixed response: the first part is JSON metadata (song ID, duration, seed, etc.) and the second part is binary audio. Use with_timestamps to get precise timing for each word in the lyrics.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/music/compose/detailed' \
  --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,
  "with_timestamps": 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/detailed' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string",
  "composition_plan": {},
  "duration": 30,
  "output_format": "mp3_44100_192",
  "sign_with_c2pa": false,
  "with_timestamps": false
}'

Request body required

Music composition parameters with optional timestamps

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

with_timestampsboolean

Include word-level timestamps in the metadata response.

Default: false

Responses

200Audio and metadata generated successfully. Response is multipart/mixed: JSON metadata followed by binary audio.

multipart/mixed

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 with metadata and optional word-level timestamps. Returns a multipart/mixed response: the first part is JSON metadata (song ID, duration, seed, etc.) and the second part is binary audio. Use with_timestamps to get precise timing for each word in the lyrics.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Music composition parameters with optional timestamps",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicComposeDetailedRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Audio and metadata generated successfully. Response is multipart/mixed: JSON metadata followed by binary audio.",
      "content": {
        "multipart/mixed": {
          "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"
          }
        }
      }
    }
  }
}