# ElevenLabs Music V2.5 Generation > Audio Generation Generate a complete song and return the audio bytes directly. Use either `input` + `music_length_ms`, or `composition_plan` with `chunks`. The `X-Song-Id` response header carries the generated song ID. When the request sets `store_for_inpainting: true`, that ID can later be referenced in `composition_plan.chunks[].conditioning_ref.song_id`. ## Endpoint `POST https://api.modelverse.cn/v1/audio/music/generate` ## Request Body ## Responses - **200** — Generated audio bytes. - **400** — - **default** — ## OpenAPI Definition ```json { "openapi": "3.1.0", "x-language": "en-US", "info": { "title": "ModelVerse ElevenLabs Music V2.5 API", "version": "1.0.0", "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse ElevenLabs\n`music-v2.5` music generation endpoints.\n\nEndpoints: `POST /v1/audio/music/generate`, `POST /v1/audio/music/stream`,\n`POST /v1/audio/music/detailed`, `POST /v1/audio/music/plan`.\n\n## Differences from music-v1\n\n| Capability | music-v1 | music-v2.5 |\n|------------|----------|------------|\n| Plan structure | `composition_plan.sections` | `composition_plan.chunks` |\n| Section duration control | `respect_sections_durations` toggles it | Always enforced, the field is ignored |\n| Audio conditioning | Not supported | `chunks[].conditioning_ref` (inpainting) |\n| Store song for inpainting | Not supported | `store_for_inpainting: true` plus the `X-Song-Id` response header |\n| Waveform visual | Not supported | `with_waveform_visual` on `/v1/audio/music/detailed` |\n| Default output format | `mp3_44100_128` | `mp3_48000_192` (override with `output_format`) |\n\n> Upstream has marked `music_v1` as deprecated; new integrations should use `music-v2.5`.\n\n## Generation modes\n\n- `input` mode: generate music from a natural-language description. `music_length_ms` is\n required (3000-600000).\n- `composition_plan` mode: control every segment through `chunks` (lyrics, duration, styles).\n `music_length_ms` must not be provided; the total duration is the sum of `chunks[].duration_ms`.\n\n`input` and `composition_plan` are mutually exclusive.\n\n## Billing\n\nBilling is based on the generated duration: `music_length_ms`, or the sum of\n`composition_plan.chunks[].duration_ms`, rounded up to whole seconds.\n`/v1/audio/music/plan` only creates a composition plan and is **not billed**\n(an audit record is still written).\n\n## Validation performed by the gateway\n\nThe following return `400` without calling upstream:\n\n- `input` and `composition_plan` provided together;\n- `music_length_ms` provided with `composition_plan`;\n- `music_length_ms` missing or outside 3000-600000 in `input` mode;\n- `seed` combined with `input` (`seed` only works with `composition_plan`);\n- `force_instrumental` combined with `composition_plan` (`input` only);\n- more than 30 chunks, a chunk without `text`/`positive_styles`, a chunk `duration_ms`\n outside 3000-120000, or a total duration above 600000.\n" }, "servers": [ { "url": "https://api.modelverse.cn", "description": "ModelVerse API endpoint shown in the source document." } ], "tags": [ { "name": "ElevenLabs Music V2.5", "description": "ElevenLabs `music-v2.5` music generation and composition-plan APIs." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/audio/music/generate": { "post": { "tags": [ "ElevenLabs Music V2.5" ], "operationId": "createElevenLabsMusicV25Generation", "summary": "ElevenLabs Music V2.5 Generation", "description": "Generate a complete song and return the audio bytes directly.\n\nUse either `input` + `music_length_ms`, or `composition_plan` with `chunks`.\n\nThe `X-Song-Id` response header carries the generated song ID. When the request sets\n`store_for_inpainting: true`, that ID can later be referenced in\n`composition_plan.chunks[].conditioning_ref.song_id`.\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25GenerationRequest" }, "examples": { "promptMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePromptRequest" }, "compositionPlanMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePlanRequest" } } } } }, "responses": { "200": { "description": "Generated audio bytes.", "headers": { "X-Song-Id": { "description": "Unique identifier of the generated song (the gateway renames the upstream `song-id` header to `X-Song-Id`).", "schema": { "type": "string" } } }, "content": { "audio/mpeg": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary" }, "examples": { "generatedMp3": { "summary": "Generated MP3 bytes", "value": "" } } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary" }, "examples": { "generatedAudio": { "summary": "Generated audio bytes", "value": "" } } } } }, "400": { "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest" }, "default": { "$ref": "#/components/responses/ElevenLabsMusicV25Error" } } } }, "/v1/audio/music/stream": { "post": { "tags": [ "ElevenLabs Music V2.5" ], "operationId": "streamElevenLabsMusicV25Generation", "summary": "ElevenLabs Music V2.5 Streaming", "description": "Stream the generated audio while it is being produced. The request body is identical to\n`/v1/audio/music/generate`. `with_timestamps`, `with_waveform_visual` and\n`respect_sections_durations` are not supported on this endpoint and will be rejected upstream.\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25GenerationRequest" }, "examples": { "promptMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25StreamRequest" }, "compositionPlanMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25GeneratePlanRequest" } } } } }, "responses": { "200": { "description": "Streamed audio bytes.", "headers": { "X-Song-Id": { "description": "Unique identifier of the generated song (the gateway renames the upstream `song-id` header to `X-Song-Id`).", "schema": { "type": "string" } } }, "content": { "audio/mpeg": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary" }, "examples": { "streamedMp3": { "summary": "Streamed MP3 bytes", "value": "" } } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary" }, "examples": { "streamedAudio": { "summary": "Streamed audio bytes", "value": "" } } } } }, "400": { "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest" }, "default": { "$ref": "#/components/responses/ElevenLabsMusicV25Error" } } } }, "/v1/audio/music/detailed": { "post": { "tags": [ "ElevenLabs Music V2.5" ], "operationId": "createElevenLabsMusicV25DetailedGeneration", "summary": "ElevenLabs Music V2.5 Metadata Generation", "description": "Generate a song and return a `multipart/mixed` response: a JSON metadata part (the\n`composition_plan` actually used plus `song_metadata`) and an audio binary part.\nThe response is passed through from upstream unchanged, so the client must parse the\nmultipart boundary itself.\n\nThis is the only endpoint that supports `with_timestamps` and `with_waveform_visual`.\n`respect_sections_durations` has no effect with `music-v2.5` and is dropped by the gateway.\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedRequest" }, "examples": { "promptMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25DetailedRequest" }, "compositionPlanMusic": { "$ref": "#/components/examples/ElevenLabsMusicV25DetailedPlanRequest" } } } } }, "responses": { "200": { "description": "Multipart response containing metadata JSON and audio bytes.", "headers": { "X-Song-Id": { "description": "Unique identifier of the generated song (the gateway renames the upstream `song-id` header to `X-Song-Id`).", "schema": { "type": "string" } } }, "content": { "multipart/mixed": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedMultipartResponse" }, "examples": { "detailedMultipart": { "$ref": "#/components/examples/ElevenLabsMusicV25DetailedMultipartResponse" } } } } }, "400": { "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest" }, "default": { "$ref": "#/components/responses/ElevenLabsMusicV25Error" } } } }, "/v1/audio/music/plan": { "post": { "tags": [ "ElevenLabs Music V2.5" ], "operationId": "createElevenLabsMusicV25CompositionPlan", "summary": "ElevenLabs Music V2.5 Composition Plan", "description": "Create a structured composition plan (`chunks`) from a text description. The result can be\npassed directly as `composition_plan` to `/v1/audio/music/generate`. This endpoint is not billed.\n\nThe body is forwarded as-is (only the public `model` field is rewritten into the upstream\n`model_id`), so `source_composition_plan` must use the v2 `chunks` structure; the v1\n`sections` structure is rejected upstream.\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25PlanRequest" }, "examples": { "popSongPlan": { "$ref": "#/components/examples/ElevenLabsMusicV25PlanRequest" }, "basedOnExistingPlan": { "$ref": "#/components/examples/ElevenLabsMusicV25PlanFromSourceRequest" } } } } }, "responses": { "200": { "description": "The generated composition plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan" }, "examples": { "popSongPlan": { "$ref": "#/components/examples/ElevenLabsMusicV25PlanResponse" } } } } }, "400": { "$ref": "#/components/responses/ElevenLabsMusicV25InvalidRequest" }, "default": { "$ref": "#/components/responses/ElevenLabsMusicV25Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Bearer authentication with an API key, formatted as `Authorization: Bearer `.\n" } }, "responses": { "ElevenLabsMusicV25InvalidRequest": { "description": "Invalid request parameters, for example `input` together with `composition_plan`,\n`music_length_ms` provided in `composition_plan` mode, `music_length_ms` out of range,\n`seed` combined with `input`, or an invalid `chunks` structure.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorResponse" }, "examples": { "invalidMusicLength": { "$ref": "#/components/examples/ElevenLabsMusicV25InvalidRequestError" } } } } }, "ElevenLabsMusicV25Error": { "description": "Upstream error. Music endpoints try to extract the readable reason from the upstream\n`{\"detail\":[{\"msg\":\"...\",\"loc\":[...]}]}` payload and pass it through so the client can\nlocate the problem (for example a `composition_plan` that does not match `model_id`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorResponse" }, "examples": { "error": { "$ref": "#/components/examples/ElevenLabsMusicV25InvalidRequestError" } } } } } }, "schemas": { "ElevenLabsMusicV25Model": { "type": "string", "const": "music-v2.5", "description": "Model name, always `music-v2.5`." }, "ElevenLabsMusicV25Input": { "type": "string", "maxLength": 4100, "description": "Music description prompt, at most 4100 characters. Mutually exclusive with `composition_plan`.", "examples": [ "A warm pop song with layered harmonies and a steady groove" ] }, "ElevenLabsMusicV25Prompt": { "type": "string", "maxLength": 4100, "description": "Composition-plan description prompt, at most 4100 characters. Only used by `/v1/audio/music/plan`.", "examples": [ "A mid-tempo pop song with a catchy chorus and warm synths" ] }, "ElevenLabsMusicV25LengthMs": { "type": "integer", "minimum": 3000, "maximum": 600000, "description": "Music duration in milliseconds, 3000-600000. Required in `input` mode and forbidden in\n`composition_plan` mode (a `400` is returned).\n", "examples": [ 30000 ] }, "ElevenLabsMusicV25PlanLengthMs": { "type": "integer", "minimum": 3000, "maximum": 600000, "description": "Target composition-plan duration in milliseconds, 3000-600000. Optional; the model decides when omitted. Only used by `/v1/audio/music/plan`.", "examples": [ 45000 ] }, "ElevenLabsMusicV25Seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Random seed, 0-2147483647, used to reproduce the same result.\nOnly valid together with `composition_plan`; combining it with `input` returns `400`.\n", "examples": [ 12345 ] }, "ElevenLabsMusicV25OutputFormat": { "type": "string", "default": "auto", "description": "Output audio format as `codec_sample_rate_bitrate`. Defaults to `auto`, which makes upstream\nchoose `mp3_48000_192` for `music-v2.5`. The gateway converts this field into the upstream\nquery parameter, so no URL rewriting is needed on the client side.\n\nSupported values: `auto`, `mp3_48000_128`, `mp3_48000_192`, `mp3_48000_240`, `mp3_48000_320`,\n`mp3_22050_32`, `mp3_24000_48`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`,\n`mp3_44100_192`, `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`,\n`pcm_48000`, `ulaw_8000`, `alaw_8000`, `opus_48000_32`, `opus_48000_64`, `opus_48000_96`,\n`opus_48000_128`, `opus_48000_192`.\n", "examples": [ "mp3_48000_192" ] }, "ElevenLabsMusicV25StoreForInpainting": { "type": "boolean", "default": false, "description": "Whether to store the generated song so it can be referenced later for inpainting. Defaults to\n`false`. When `true`, the song ID from the `X-Song-Id` response header can be used as\n`composition_plan.chunks[].conditioning_ref.song_id` in a later request.\nSupported by `/v1/audio/music/generate`, `/v1/audio/music/stream` and `/v1/audio/music/detailed`.\n" }, "ElevenLabsMusicV25WithTimestamps": { "type": "boolean", "default": false, "description": "Whether to return lyric timestamps. Defaults to `false`. Only supported by `/v1/audio/music/detailed`; other endpoints reject it upstream." }, "ElevenLabsMusicV25WithWaveformVisual": { "type": "boolean", "default": false, "description": "Whether to return waveform visual data. Defaults to `false`. Only supported by `/v1/audio/music/detailed`; other endpoints reject it upstream." }, "ElevenLabsMusicV25RespectSectionsDurations": { "type": "boolean", "description": "Whether to strictly follow chunk durations. **Only applies to `music-v1`**: with `music-v2.5`\nchunk durations are always enforced, so the gateway drops this field before forwarding.\nIt is kept only for clients migrating from `music-v1`.\n" }, "ElevenLabsMusicV25GenerationRequest": { "description": "Music generation request body. Provide either `input` or `composition_plan`:\n- `input` mode: `music_length_ms` is required and defines the duration;\n- `composition_plan` mode: `music_length_ms` is forbidden and the duration is the sum of the\n chunk durations.\n", "oneOf": [ { "$ref": "#/components/schemas/ElevenLabsMusicV25PromptGenerationRequest" }, { "$ref": "#/components/schemas/ElevenLabsMusicV25PlanGenerationRequest" } ] }, "ElevenLabsMusicV25PromptGenerationRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "input", "music_length_ms" ], "properties": { "model": { "$ref": "#/components/schemas/ElevenLabsMusicV25Model" }, "input": { "$ref": "#/components/schemas/ElevenLabsMusicV25Input" }, "music_length_ms": { "$ref": "#/components/schemas/ElevenLabsMusicV25LengthMs" }, "force_instrumental": { "type": "boolean", "default": false, "description": "Force instrumental-only output. Defaults to `false`. Only valid with `input`; combining it with `composition_plan` returns `400`." }, "store_for_inpainting": { "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting" }, "output_format": { "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat" } } }, "ElevenLabsMusicV25PlanGenerationRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "composition_plan" ], "properties": { "model": { "$ref": "#/components/schemas/ElevenLabsMusicV25Model" }, "composition_plan": { "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan" }, "seed": { "$ref": "#/components/schemas/ElevenLabsMusicV25Seed" }, "store_for_inpainting": { "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting" }, "output_format": { "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat" } }, "description": "composition_plan mode. `music_length_ms` must not be provided, otherwise `400` is returned.\nThe billed duration is the sum of `composition_plan.chunks[].duration_ms`.\n" }, "ElevenLabsMusicV25DetailedRequest": { "description": "Detailed generation request body. Provide either `input` or `composition_plan`:\n- `input` mode: `music_length_ms` is required;\n- `composition_plan` mode: `music_length_ms` is forbidden.\n", "oneOf": [ { "$ref": "#/components/schemas/ElevenLabsMusicV25PromptDetailedRequest" }, { "$ref": "#/components/schemas/ElevenLabsMusicV25PlanDetailedRequest" } ] }, "ElevenLabsMusicV25PromptDetailedRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "input", "music_length_ms" ], "properties": { "model": { "$ref": "#/components/schemas/ElevenLabsMusicV25Model" }, "input": { "$ref": "#/components/schemas/ElevenLabsMusicV25Input" }, "music_length_ms": { "$ref": "#/components/schemas/ElevenLabsMusicV25LengthMs" }, "force_instrumental": { "type": "boolean", "default": false, "description": "Force instrumental-only output. Defaults to `false`. Only valid with `input`." }, "with_timestamps": { "$ref": "#/components/schemas/ElevenLabsMusicV25WithTimestamps" }, "with_waveform_visual": { "$ref": "#/components/schemas/ElevenLabsMusicV25WithWaveformVisual" }, "store_for_inpainting": { "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting" }, "output_format": { "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat" } } }, "ElevenLabsMusicV25PlanDetailedRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "composition_plan" ], "properties": { "model": { "$ref": "#/components/schemas/ElevenLabsMusicV25Model" }, "composition_plan": { "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan" }, "seed": { "$ref": "#/components/schemas/ElevenLabsMusicV25Seed" }, "with_timestamps": { "$ref": "#/components/schemas/ElevenLabsMusicV25WithTimestamps" }, "with_waveform_visual": { "$ref": "#/components/schemas/ElevenLabsMusicV25WithWaveformVisual" }, "respect_sections_durations": { "$ref": "#/components/schemas/ElevenLabsMusicV25RespectSectionsDurations" }, "store_for_inpainting": { "$ref": "#/components/schemas/ElevenLabsMusicV25StoreForInpainting" }, "output_format": { "$ref": "#/components/schemas/ElevenLabsMusicV25OutputFormat" } }, "description": "composition_plan mode. `music_length_ms` must not be provided, otherwise `400` is returned.\n" }, "ElevenLabsMusicV25PlanRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "prompt" ], "properties": { "model": { "$ref": "#/components/schemas/ElevenLabsMusicV25Model" }, "prompt": { "$ref": "#/components/schemas/ElevenLabsMusicV25Prompt" }, "music_length_ms": { "$ref": "#/components/schemas/ElevenLabsMusicV25PlanLengthMs" }, "source_composition_plan": { "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan" } } }, "ElevenLabsMusicV25CompositionPlan": { "type": "object", "additionalProperties": false, "required": [ "chunks" ], "description": "The `music-v2.5` composition plan, made of up to 30 `chunks`. The chunk durations are summed\ninto the total duration, which must not exceed 600000 ms.\n\nThis structure is exclusive to `music-v2` / `music-v2.5`; `music-v1` uses `sections` and\nmixing the two is rejected upstream.\n", "properties": { "chunks": { "type": "array", "maxItems": 30, "description": "Ordered list of chunks (required, at most 30).", "items": { "$ref": "#/components/schemas/ElevenLabsMusicV25Chunk" } } } }, "ElevenLabsMusicV25Chunk": { "type": "object", "additionalProperties": false, "required": [ "text", "duration_ms", "positive_styles" ], "properties": { "text": { "type": "string", "maxLength": 6132, "description": "Lyrics and directions for this chunk (required). An optional section name may be given in\nsquare brackets at the beginning, for example `[Verse 1]` (1-100 characters), and inline\ndirections in curly braces, for example `{very loud}`. At most 30 lines, each at most 200\ncharacters. Instrumental chunks can use a label such as `[Instrumental Outro]`.\n", "examples": [ "[Verse]\nCity lights are fading\nWe keep moving through the night\n" ] }, "duration_ms": { "type": "integer", "minimum": 3000, "maximum": 120000, "description": "Duration of this chunk in milliseconds (required), 3000-120000. The sum over all chunks must not exceed 600000.", "examples": [ 15000 ] }, "positive_styles": { "type": "array", "maxItems": 50, "description": "Styles and musical directions that should be present in this chunk (required, at most 50).\nEnglish works best. The first chunk matters most because it sets the tone and genre;\naim for at least 6-7 styles in the early chunks.\n", "items": { "type": "string" }, "examples": [ [ "pop", "warm synths", "steady groove", "layered harmonies" ] ] }, "negative_styles": { "type": "array", "maxItems": 50, "description": "Styles and musical directions that should not be present in this chunk (optional, at most 50). Leaving it empty is the default.", "items": { "type": "string" }, "examples": [ [ "heavy metal", "harsh distortion" ] ] }, "context_adherence": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "high", "description": "How closely the model follows the surrounding chunks. Defaults to `high`. `low` allows more\ncreative deviation, `high` keeps the chunk consistent with its context.\n" }, "conditioning_ref": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioRefChunk" }, "condition_strength": { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ], "description": "How strongly the model adheres to `conditioning_ref`. `low` is more creative and deviates\nfrom the reference, `xhigh` reproduces it as closely as possible. The first chunk influences\nthe whole song, so start conditioning from it if the entire song should follow the reference.\n" } }, "description": "A composition chunk. The first chunk sets the tone and genre; later chunks can add nuance,\nprogression, emphasis or change direction. For inpainting, set `conditioning_ref` to a\npreviously stored song ID (from the `X-Song-Id` response header of a generation made with\n`store_for_inpainting: true`).\n" }, "ElevenLabsMusicV25AudioRefChunk": { "type": "object", "additionalProperties": false, "required": [ "song_id", "range" ], "description": "References a time range of a previously stored song as conditioning audio.", "properties": { "song_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "ID of the referenced song, taken from the `X-Song-Id` response header of the generation that produced it.", "examples": [ "song_abc123" ] }, "range": { "$ref": "#/components/schemas/ElevenLabsMusicV25TimeRange" } } }, "ElevenLabsMusicV25TimeRange": { "type": "object", "additionalProperties": false, "required": [ "start_ms", "end_ms" ], "description": "Time range of the reference audio in milliseconds.", "properties": { "start_ms": { "type": "integer", "description": "Start offset in milliseconds.", "examples": [ 0 ] }, "end_ms": { "type": "integer", "description": "End offset in milliseconds.", "examples": [ 10000 ] } } }, "ElevenLabsMusicV25DetailedMetadata": { "type": "object", "additionalProperties": true, "required": [ "composition_plan", "song_metadata" ], "properties": { "composition_plan": { "$ref": "#/components/schemas/ElevenLabsMusicV25CompositionPlan" }, "song_metadata": { "$ref": "#/components/schemas/ElevenLabsMusicV25SongMetadata" } } }, "ElevenLabsMusicV25SongMetadata": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "Song title.", "examples": [ "City Lights" ] }, "description": { "type": "string", "description": "Song description.", "examples": [ "A warm mid-tempo pop song with layered harmonies" ] }, "genres": { "type": "array", "description": "Music genres.", "items": { "type": "string" }, "examples": [ [ "pop" ] ] }, "languages": { "type": "array", "description": "Languages used in the lyrics.", "items": { "type": "string" }, "examples": [ [ "en" ] ] }, "is_explicit": { "type": "boolean", "description": "Whether the song is explicit." } } }, "ElevenLabsMusicV25AudioBinary": { "type": "string", "format": "binary", "description": "Generated audio bytes; the format follows `output_format`, and `auto` resolves to `mp3_48000_192` for `music-v2.5`." }, "ElevenLabsMusicV25DetailedMultipartResponse": { "type": "object", "additionalProperties": false, "required": [ "metadata", "audio" ], "properties": { "metadata": { "$ref": "#/components/schemas/ElevenLabsMusicV25DetailedMetadata" }, "audio": { "$ref": "#/components/schemas/ElevenLabsMusicV25AudioBinary" } }, "description": "The `multipart/mixed` response of `/v1/audio/music/detailed`: a JSON metadata part (the\ncomposition plan used plus song metadata) and an audio binary part. It is passed through from\nupstream unchanged; when `with_timestamps` or `with_waveform_visual` is enabled the extra\nfields appear inside the metadata part.\n" }, "ElevenLabsMusicV25ErrorResponse": { "type": "object", "additionalProperties": true, "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ElevenLabsMusicV25ErrorObject" } } }, "ElevenLabsMusicV25ErrorObject": { "type": "object", "additionalProperties": true, "required": [ "message", "type" ], "properties": { "message": { "type": "string", "description": "Human readable error. Upstream validation errors include the failing location, for example `composition_plan.chunks.0.duration_ms: Input should be ...`.", "examples": [ "music_length_ms must be between 3000 and 600000" ] }, "type": { "type": "string", "description": "Error type.", "examples": [ "invalid_request_error" ] }, "code": { "type": [ "string", "null" ], "description": "Machine readable error code.", "examples": [ "param_error" ] }, "param": { "type": [ "string", "null" ], "description": "Request parameter related to the error.", "examples": [ "music_length_ms" ] } } } }, "examples": { "ElevenLabsMusicV25GeneratePromptRequest": { "summary": "Generate music from a text prompt (input mode)", "value": { "model": "music-v2.5", "input": "A warm pop song with layered harmonies and a steady groove", "music_length_ms": 30000, "output_format": "mp3_48000_192", "store_for_inpainting": true } }, "ElevenLabsMusicV25GeneratePlanRequest": { "summary": "Generate music from a composition plan (chunks mode)", "description": "composition_plan mode example. `music_length_ms` must not be provided; the total duration is\nthe sum of the chunk durations (35 seconds here).\n", "value": { "model": "music-v2.5", "composition_plan": { "chunks": [ { "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n", "duration_ms": 15000, "positive_styles": [ "pop", "warm synths", "steady groove", "layered harmonies" ] }, { "text": "[Chorus]\nHold on to the feeling\n{very loud}Let it rise and come alive\n", "duration_ms": 15000, "positive_styles": [ "uplifting", "bigger drums", "wide vocals" ] }, { "text": "[Instrumental Outro]", "duration_ms": 5000, "positive_styles": [ "gentle ending", "soft pads" ] } ] }, "seed": 12345, "output_format": "mp3_48000_192" } }, "ElevenLabsMusicV25StreamRequest": { "summary": "Stream music (input mode)", "value": { "model": "music-v2.5", "input": "A calm acoustic guitar piece with soft rain ambience", "music_length_ms": 30000, "output_format": "mp3_48000_192" } }, "ElevenLabsMusicV25DetailedRequest": { "summary": "input mode with metadata", "value": { "model": "music-v2.5", "input": "An upbeat pop tune with a catchy chorus", "music_length_ms": 30000, "with_timestamps": true, "with_waveform_visual": true } }, "ElevenLabsMusicV25DetailedPlanRequest": { "summary": "composition_plan mode with metadata", "description": "composition_plan mode example; `music_length_ms` must not be provided.", "value": { "model": "music-v2.5", "composition_plan": { "chunks": [ { "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n", "duration_ms": 15000, "positive_styles": [ "pop", "warm synths", "steady groove" ] }, { "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n", "duration_ms": 15000, "positive_styles": [ "uplifting", "bigger drums", "wide vocals" ] } ] }, "seed": 12345, "with_timestamps": false, "with_waveform_visual": true } }, "ElevenLabsMusicV25DetailedMultipartResponse": { "summary": "Multipart metadata and audio response", "value": { "metadata": { "composition_plan": { "chunks": [ { "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n", "duration_ms": 15000, "positive_styles": [ "pop", "warm synths", "steady groove" ] }, { "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n", "duration_ms": 15000, "positive_styles": [ "uplifting", "bigger drums", "wide vocals" ] } ] }, "song_metadata": { "title": "City Lights", "description": "A warm mid-tempo pop song with layered harmonies", "genres": [ "pop" ], "languages": [ "en" ], "is_explicit": false } }, "audio": "" } }, "ElevenLabsMusicV25PlanRequest": { "summary": "Create a composition plan from a description", "value": { "model": "music-v2.5", "prompt": "A mid-tempo pop song with a catchy chorus and warm synths", "music_length_ms": 45000 } }, "ElevenLabsMusicV25PlanFromSourceRequest": { "summary": "Create a new composition plan from an existing one", "description": "`source_composition_plan` must use the v2 `chunks` structure; the v1 `sections` structure is\nrejected upstream.\n", "value": { "model": "music-v2.5", "prompt": "A longer version with an extended outro and softer ending", "music_length_ms": 60000, "source_composition_plan": { "chunks": [ { "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n", "duration_ms": 15000, "positive_styles": [ "pop", "warm synths", "steady groove" ] }, { "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n", "duration_ms": 15000, "positive_styles": [ "uplifting", "bigger drums", "wide vocals" ] } ] } } }, "ElevenLabsMusicV25PlanResponse": { "summary": "Generated composition plan", "value": { "chunks": [ { "text": "[Verse]\nCity lights are fading\nWe keep moving through the night\n", "duration_ms": 15000, "positive_styles": [ "pop", "warm synths", "steady groove", "layered harmonies" ] }, { "text": "[Chorus]\nHold on to the feeling\nLet it rise and come alive\n", "duration_ms": 15000, "positive_styles": [ "uplifting", "bigger drums", "wide vocals" ] }, { "text": "[Instrumental Outro]", "duration_ms": 5000, "positive_styles": [ "gentle ending", "soft pads" ] } ] } }, "ElevenLabsMusicV25InvalidRequestError": { "summary": "Invalid parameter example", "value": { "error": { "message": "music_length_ms must be between 3000 and 600000", "type": "invalid_request_error", "code": "param_error", "param": "music_length_ms" } } } } } } ```