# Stream music

Source: https://recoupable.dev/docs/api-reference/complete/content/post-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.

## POST /api/music/stream

Full OpenAPI specification: https://recoupable.dev/docs/spec/content.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Content",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/music/stream": {
      "post": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MusicStreamRequest": {
        "type": "object",
        "description": "Parameters for generating a song with real-time audio streaming.",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Text prompt describing the desired song — mood, genre, instruments, lyrics, structure."
          },
          "composition_plan": {
            "type": "object",
            "description": "Full composition plan for fine-grained control over sections, styles, and lyrics. Use POST /api/music/plan to generate one."
          },
          "duration": {
            "type": "number",
            "description": "Desired duration in seconds.",
            "default": 30
          },
          "output_format": {
            "type": "string",
            "description": "Audio output format (e.g. mp3_44100_192).",
            "default": "mp3_44100_192"
          },
          "sign_with_c2pa": {
            "type": "boolean",
            "description": "Sign the output with C2PA content credentials.",
            "default": false
          }
        }
      },
      "MusicErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "Error response from a music endpoint.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong."
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```