API REFERENCE

Stream music

On this page

POST/api/music/stream

Generate a song and stream audio chunks in real time. Use this endpoint when you want to begin playback before the full song is generated. The response streams binary audio chunks as they are produced.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/music/stream' \
  --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
}'

Request body required

Music streaming 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 stream started 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 and stream audio chunks in real time. Use this endpoint when you want to begin playback before the full song is generated. The response streams binary audio chunks as they are produced.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Music streaming parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicStreamRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Audio stream started 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"
          }
        }
      }
    }
  }
}