> ## Documentation Index > Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # ElevenLabs Music > Compose songs or instrumentals from a text brief or a section-by-section plan, with control over musical style, lyrics, and arrangement. 1. Submit the request with `VIDGO_API_KEY`. A `task_id` is returned immediately. Keep it until the task reaches `finished` or `failed`. 2. Use [Query Task Status](/api-manual/task-management/status) to retrieve the result. If you provide a `callback_url`, Vidgo sends the result to your [webhook](/api-manual/task-management/webhooks) when the task finishes or fails. # ElevenLabs Music Compose songs or instrumentals from a text brief or a section-by-section plan, with control over musical style, lyrics, and arrangement. ## Available Models * **elevenlabs/music** - Generate music from text or a structured composition plan. ## Duration Options * **Text input** - Optional `duration` is a number from **3 to 600 seconds**. Use it only with `text`. * **Composition plan** - Each section accepts **3-120 seconds**. ## Output Options ### Output Format * `output_format`: Optional. String. Default: `mp3_44100_128`. - `mp3_22050_32` - `mp3_44100_32` - `mp3_44100_64` - `mp3_44100_96` - `mp3_44100_128` - `mp3_44100_192` - `pcm_8000` - `pcm_16000` - `pcm_22050` - `pcm_24000` - `pcm_44100` - `pcm_48000` - `ulaw_8000` - `alaw_8000` - `opus_48000_32` - `opus_48000_64` - `opus_48000_96` - `opus_48000_128` - `opus_48000_192` ## Key Features * Generate music from text or a structured composition plan. * Plan musical sections with their own styles, lyrics, and durations. * Choose an output encoding with `output_format`. ## Advanced Parameters Set `model` and optional `callback_url` at the request root. Place all workflow parameters, including output options, inside `input`. Choose one creative path: a text brief or a structured composition plan. * Provide exactly one of `text` or `composition_plan`. * `duration` and `is_instrumental` apply only to `text`. Use `respect_sections_durations` only with `composition_plan`. ### Text * `text`: Required for the text path. Describe the music to generate. Length: **1-4,100 characters**. * Include a music description with the desired genre, mood, and instruments. ### Composition Plan * `composition_plan`: Required for the composition-plan path. Describe global styles and an ordered list of musical sections. Supply an object with the fields below. * `composition_plan.positive_global_styles`: Required. Supply an array. Each item must be a string. * `composition_plan.negative_global_styles`: Required. Supply an array. Each item must be a string. * `composition_plan.sections`: Required. Supply at least 1 item. Each item is an object. * `composition_plan.sections[].section_name`: Required. Length: **1-100 characters**. * `composition_plan.sections[].positive_local_styles`: Required. Supply an array. Each item must be a string. * `composition_plan.sections[].negative_local_styles`: Required. Supply an array. Each item must be a string. * `composition_plan.sections[].duration`: Required. Duration in seconds. Number from `3` to `120`. * `composition_plan.sections[].lines`: Required. Supply an array. Each item must be a string. Each string is limited to **200 characters**. * Section durations are measured in seconds. ### Instrumental Mode * `is_instrumental`: Optional. Request instrumental music with `true`. Default: `false` for the text path. * Use only with `text`. ### Section Timing * `respect_sections_durations`: Optional. Use only with a composition plan to control adherence to section durations. Use `true` or `false`. Default: `true` for the composition-plan path. ## Output Files * Read every item in the returned `files` array. * Generated audio uses `file_type: "audio"`. * Timestamp and alignment files may use `file_type: "other"`. Preserve optional file metadata when present. ## Examples Each example pairs a request with its completed task response and generated audio. Submit the request to `POST https://api.vidgo.ai/api/generate/submit`, then query `GET https://api.vidgo.ai/api/generate/status/{task_id}` with the task ID returned by your submission. ```json Request theme={null} { "model": "elevenlabs/music", "input": { "composition_plan": { "positive_global_styles": [ "indie folk with subtle organic electronica", "96 BPM, 4/4", "warm clear female lead vocal", "acoustic guitar, rounded bass, delicate electronic percussion", "hopeful intimate song about planting a rooftop garden", "clean spacious studio mix, clear Mandarin and English diction" ], "negative_global_styles": [ "harsh distortion", "crowded arrangement", "spoken narration", "abrupt cut off" ], "sections": [ { "section_name": "Acoustic introduction", "duration": 8, "positive_local_styles": [ "instrumental only", "fingerpicked acoustic guitar introduces a memorable gentle motif", "soft airy pad, no drums" ], "negative_local_styles": [], "lines": [] }, { "section_name": "Mandarin verse", "duration": 16, "positive_local_styles": [ "sing the supplied Mandarin lyrics clearly", "intimate gentle lead vocal", "fingerpicked guitar and soft bass, restrained percussion" ], "negative_local_styles": [], "lines": [ "把春天种在屋顶上", "等风翻过旧砖墙" ] }, { "section_name": "English chorus", "duration": 16, "positive_local_styles": [ "sing the supplied English lyrics clearly", "open uplifting melody", "full warm drums and bass enter", "layered backing vocal harmonies, retain the acoustic motif" ], "negative_local_styles": [], "lines": [ "Little seeds above the street", "Find the sunlight, find the beat" ] }, { "section_name": "Instrumental resolution", "duration": 8, "positive_local_styles": [ "instrumental only, no vocals", "return to fingerpicked guitar motif", "drums fall away, warm sustained final chord with natural decay" ], "negative_local_styles": [], "lines": [] } ] }, "respect_sections_durations": true, "output_format": "mp3_44100_128" } } ``` ```json Completed task response theme={null} { "code": 200, "data": { "task_id": "W6KDNIQQOUAE1K8V", "status": "finished", "created_time": "2026-09-27T10:48:12", "progress": 100, "error_message": null, "files": [ { "file_type": "audio", "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/01/output.mp3" } ] } } ``` ```json Request theme={null} { "model": "elevenlabs/music", "input": { "text": "Create a 30-second instrumental jazz cue for a puzzle scene in a clockmaker's workshop. 104 BPM, lightly swinging 4/4, playful curiosity with a hint of mystery. Use plucked upright bass, brushed drums, muted trumpet and vibraphone, each clearly separated in a warm intimate acoustic mix. Begin with a distinctive four-note vibraphone motif over bass; let muted trumpet answer and develop that motif in the middle, while brush accents subtly increase the momentum. Resolve with a short, clean ensemble cadence and allow the last note to decay naturally. No vocals, choir, spoken words, ticking sound effects or abrupt cutoff.", "duration": 30, "is_instrumental": true, "output_format": "mp3_44100_128" } } ``` ```json Completed task response theme={null} { "code": 200, "data": { "task_id": "EBXJLNFGE8WD7114", "status": "finished", "created_time": "2026-09-27T10:48:48", "progress": 100, "error_message": null, "files": [ { "file_type": "audio", "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/02/output.mp3" } ] } } ``` ```json Request theme={null} { "model": "elevenlabs/music", "input": { "text": "Compose a 40-second instrumental score for a nature documentary gliding through a sunlit underwater kelp forest. 72 BPM, gently flowing 4/4. Felt piano, delicate harp harmonics, soft sustained strings and a subtle low ambient texture; luminous, patient, full of quiet wonder. Start sparsely with isolated felt-piano notes and wide space. Gradually introduce harp and strings into an expansive rising harmony through the middle third, suggesting shafts of light moving through long fronds. Gently thin the arrangement and finish on a peaceful resolved chord with natural reverb decay. Detailed soft dynamics, wide stereo depth, no heavy percussion, no vocals or choir, no narration, no water sound effects, no abrupt cutoff.", "duration": 40, "is_instrumental": true, "output_format": "mp3_44100_128" } } ``` ```json Completed task response theme={null} { "code": 200, "data": { "task_id": "VAK9IGFH57XPEUGP", "status": "finished", "created_time": "2026-09-27T10:49:30", "progress": 100, "error_message": null, "files": [ { "file_type": "audio", "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/03/output.mp3" } ] } } ``` ## OpenAPI ````yaml api-manual/music-series/elevenlabs-music.json POST /api/generate/submit openapi: 3.0.0 info: title: Vidgo API - ElevenLabs Music description: >- Compose songs or instrumentals from a text brief or a section-by-section plan, with control over musical style, lyrics, and arrangement. version: 1.0.0 servers: - url: https://api.vidgo.ai security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Audio Series summary: ElevenLabs Music description: >- Compose music using one creative path: text or composition_plan. With text, set duration and is_instrumental. With composition_plan, set respect_sections_durations. Each section duration is measured in seconds. Read the generated audio from files entries with file_type=audio; preserve accompanying file metadata. operationId: submit_elevenlabs_music requestBody: required: true content: application/json: schema: type: object required: - model - input additionalProperties: true properties: model: type: string example: elevenlabs/music enum: - elevenlabs/music input: type: object additionalProperties: false properties: text: type: string maxLength: 4100 minLength: 1 description: >- Music description, 1-4100 characters. Required for the text path. composition_plan: type: object required: - positive_global_styles - negative_global_styles - sections additionalProperties: false properties: positive_global_styles: type: array items: type: string description: Positive global styles. description: >- Musical styles to include throughout the track. Use an empty array when no global styles are specified. negative_global_styles: type: array items: type: string description: Negative global styles. description: >- Musical styles to exclude throughout the track. An empty array is valid. sections: type: array minItems: 1 items: type: object required: - section_name - positive_local_styles - negative_local_styles - duration - lines additionalProperties: false properties: section_name: type: string minLength: 1 maxLength: 100 description: >- Name of this musical section, such as Intro, Verse, or Chorus; 1-100 characters. positive_local_styles: type: array items: type: string description: Positive local styles. description: >- Musical styles and instruments to include in this section. An empty array is valid. negative_local_styles: type: array items: type: string description: Negative local styles. description: >- Musical styles to exclude from this section. An empty array is valid. duration: type: number minimum: 3 maximum: 120 description: >- Duration of this section in seconds, from 3 to 120, including decimals. lines: type: array items: type: string maxLength: 200 description: One lyric line of up to 200 characters. description: >- Lyrics for this section, one string per line, up to 200 characters per line. Use an empty array for an instrumental section. description: Sections. description: >- At least one musical section, ordered by its position in the track. description: >- Structured global styles and musical sections. Required for the composition-plan path. duration: type: number minimum: 3 maximum: 600 description: >- Song duration in seconds, from 3 to 600, including decimals. Applies to text input. is_instrumental: type: boolean description: >- Set true to generate instrumental music. Applies to text input; defaults to false in that path. default: false respect_sections_durations: type: boolean description: >- Follow the specified section timings. Applies to composition_plan; defaults to true in that path. default: true output_format: type: string enum: - mp3_22050_32 - mp3_44100_32 - mp3_44100_64 - mp3_44100_96 - mp3_44100_128 - mp3_44100_192 - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 - alaw_8000 - opus_48000_32 - opus_48000_64 - opus_48000_96 - opus_48000_128 - opus_48000_192 default: mp3_44100_128 description: >- Audio encoding, sample rate, and bitrate. Default: mp3_44100_128. description: >- Provide exactly one of `text` or `composition_plan`. With `text`, omit `respect_sections_durations`. With `composition_plan`, omit `duration` and `is_instrumental`. callback_url: type: string nullable: true description: >- Optional public HTTP(S) endpoint for task completion notifications. HTTPS is recommended. Omit, use null, or use an empty string to disable callbacks. description: >- Set model and optional callback_url at the root. Place the creative path and its controls inside input. examples: basic: summary: Spring on the Rooftop value: model: elevenlabs/music input: composition_plan: positive_global_styles: - indie folk with subtle organic electronica - 96 BPM, 4/4 - warm clear female lead vocal - >- acoustic guitar, rounded bass, delicate electronic percussion - hopeful intimate song about planting a rooftop garden - >- clean spacious studio mix, clear Mandarin and English diction negative_global_styles: - harsh distortion - crowded arrangement - spoken narration - abrupt cut off sections: - section_name: Acoustic introduction duration: 8 positive_local_styles: - instrumental only - >- fingerpicked acoustic guitar introduces a memorable gentle motif - soft airy pad, no drums negative_local_styles: [] lines: [] - section_name: Mandarin verse duration: 16 positive_local_styles: - sing the supplied Mandarin lyrics clearly - intimate gentle lead vocal - >- fingerpicked guitar and soft bass, restrained percussion negative_local_styles: [] lines: - 把春天种在屋顶上 - 等风翻过旧砖墙 - section_name: English chorus duration: 16 positive_local_styles: - sing the supplied English lyrics clearly - open uplifting melody - full warm drums and bass enter - >- layered backing vocal harmonies, retain the acoustic motif negative_local_styles: [] lines: - Little seeds above the street - Find the sunlight, find the beat - section_name: Instrumental resolution duration: 8 positive_local_styles: - instrumental only, no vocals - return to fingerpicked guitar motif - >- drums fall away, warm sustained final chord with natural decay negative_local_styles: [] lines: [] respect_sections_durations: true output_format: mp3_44100_128 clockmaker-clues: summary: The Clockmaker's Clues value: model: elevenlabs/music input: text: >- Create a 30-second instrumental jazz cue for a puzzle scene in a clockmaker's workshop. 104 BPM, lightly swinging 4/4, playful curiosity with a hint of mystery. Use plucked upright bass, brushed drums, muted trumpet and vibraphone, each clearly separated in a warm intimate acoustic mix. Begin with a distinctive four-note vibraphone motif over bass; let muted trumpet answer and develop that motif in the middle, while brush accents subtly increase the momentum. Resolve with a short, clean ensemble cadence and allow the last note to decay naturally. No vocals, choir, spoken words, ticking sound effects or abrupt cutoff. duration: 30 is_instrumental: true output_format: mp3_44100_128 kelp-forest-light: summary: Light Through the Kelp Forest value: model: elevenlabs/music input: text: >- Compose a 40-second instrumental score for a nature documentary gliding through a sunlit underwater kelp forest. 72 BPM, gently flowing 4/4. Felt piano, delicate harp harmonics, soft sustained strings and a subtle low ambient texture; luminous, patient, full of quiet wonder. Start sparsely with isolated felt-piano notes and wide space. Gradually introduce harp and strings into an expansive rising harmony through the middle third, suggesting shafts of light moving through long fronds. Gently thin the arrangement and finish on a peaceful resolved chord with natural reverb decay. Detailed soft dynamics, wide stereo depth, no heavy percussion, no vocals or choir, no narration, no water sound effects, no abrupt cutoff. duration: 40 is_instrumental: true output_format: mp3_44100_128 callback: summary: Receive a completion callback value: model: elevenlabs/music input: composition_plan: positive_global_styles: - indie folk with subtle organic electronica - 96 BPM, 4/4 - warm clear female lead vocal - >- acoustic guitar, rounded bass, delicate electronic percussion - hopeful intimate song about planting a rooftop garden - >- clean spacious studio mix, clear Mandarin and English diction negative_global_styles: - harsh distortion - crowded arrangement - spoken narration - abrupt cut off sections: - section_name: Acoustic introduction duration: 8 positive_local_styles: - instrumental only - >- fingerpicked acoustic guitar introduces a memorable gentle motif - soft airy pad, no drums negative_local_styles: [] lines: [] - section_name: Mandarin verse duration: 16 positive_local_styles: - sing the supplied Mandarin lyrics clearly - intimate gentle lead vocal - >- fingerpicked guitar and soft bass, restrained percussion negative_local_styles: [] lines: - 把春天种在屋顶上 - 等风翻过旧砖墙 - section_name: English chorus duration: 16 positive_local_styles: - sing the supplied English lyrics clearly - open uplifting melody - full warm drums and bass enter - >- layered backing vocal harmonies, retain the acoustic motif negative_local_styles: [] lines: - Little seeds above the street - Find the sunlight, find the beat - section_name: Instrumental resolution duration: 8 positive_local_styles: - instrumental only, no vocals - return to fingerpicked guitar motif - >- drums fall away, warm sustained final chord with natural decay negative_local_styles: [] lines: [] respect_sections_durations: true output_format: mp3_44100_128 callback_url: https://your-domain.com/callback responses: '200': description: Task submitted content: application/json: schema: type: object required: - code - data properties: code: type: integer enum: - 200 data: type: object required: - task_id - status - created_time properties: task_id: type: string status: type: string enum: - not_started - running - finished - failed created_time: type: string format: date-time example: code: 200 data: task_id: W6KDNIQQOUAE1K8V status: running created_time: '2026-09-27T10:48:12' '400': description: Input validation failed or the account requires additional balance content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '401': description: Invalid credentials content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '403': description: Access denied content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '404': description: Unknown or disabled model content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '408': description: Request timed out content: text/plain: schema: type: string example: Request timeout '422': description: Invalid JSON or non-object request body content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '429': description: Rate or API key credit limit exceeded content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '500': description: Internal error content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '502': description: Unable to create the upstream generation task content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} '503': description: Model configuration or capability is not approved content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} components: securitySchemes: BearerAuth: type: http scheme: bearer description: Use VIDGO_API_KEY. ````