Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/elevenlabs/llms.txt

Use this file to discover all available pages before exploring further.

The Music resource exposes the full surface of ElevenLabs’ music generation APIs from a single, coherent PHP interface. You can compose tracks directly from a text prompt, break the process into two steps by generating a composition plan first, receive rich metadata alongside the audio, derive a synchronized score from one or more video files, isolate individual stems from a mixed track, and upload source audio for use in composition-plan and inpainting workflows. Every method is available on both the configured provider instance and the static facade. 
use AiSdk\ElevenLabs;

$music = ElevenLabs::music()->compose('Warm acoustic guitar intro with gentle rain.');
$music->output->save(__DIR__.'/intro.mp3');

​
Methods

​
compose()

The simplest path to a finished track. Supply a text prompt and any additional options; the method returns an AudioResult whose output property you can save or read directly. 
$music = ElevenLabs::music()->compose('Warm acoustic guitar intro with gentle rain.', [
    'model_id'        => 'music_v1',
    'music_length_ms' => 30_000,
]);

$music->output->save(__DIR__.'/intro.mp3');
output_format is extracted from the options array and forwarded as a query parameter before the remaining options are serialised into the JSON request body. This matches the ElevenLabs API contract. The default value when the key is omitted is 'auto'.
​
prompt
string
required
Descriptive text that guides the composition — instrumentation, mood, tempo, and structure all influence the result.
​
options
array
Additional generation options sent in the request body (except output_format, which is sent as a query parameter).
​
model_id
string
ElevenLabs music model to use. Available values: music_v1, music_v2.
​
music_length_ms
integer
Target duration of the generated track in milliseconds.
​
output_format
string
Audio encoding for the returned file (e.g. mp3_44100_128, mp3_48000_192). Defaults to 'auto'.
​
AudioResult
object
​
output
AudioData
Contains the raw audio bytes and MIME type. Call ->save($path) to write the file, or access ->data for the raw string.

​
plan()

Generate a structured composition plan without producing audio. The plan encodes the structural decisions ElevenLabs has made — sections, styles, instruments — and can be inspected or modified before you commit to rendering a track. 
$plan = ElevenLabs::music()->plan('A tense cinematic cue with a quiet ending.', [
    'model_id'        => 'music_v2',
    'music_length_ms' => 30_000,
]);

// Inspect the raw plan data
print_r($plan->value);
​
prompt
string
required
Descriptive text used to build the composition plan.
​
options
array
Additional options forwarded in the JSON request body, including model_id and music_length_ms.
​
MusicPlan
object
​
value
array
The raw composition plan returned by ElevenLabs. Pass this directly to composeFromPlan() or composeDetailedFromPlan().

​
composeFromPlan()

Render audio from an existing MusicPlan or a raw plan array. This lets you inspect or adjust the plan between steps before committing to a full render. 
$track = ElevenLabs::music()->composeFromPlan($plan, [
    'model_id'      => 'music_v2',
    'output_format' => 'mp3_48000_192',
]);

$track->output->save(__DIR__.'/track.mp3');
​
plan
MusicPlan|array
required
A MusicPlan instance returned by plan(), or a raw associative array with the same structure.
​
options
array
Generation options, including model_id and output_format.
​
AudioResult
object
​
output
AudioData
The rendered audio. Call ->save($path) or read ->data directly.

​
composeDetailed()

Compose a track and receive a DetailedMusicResult that bundles the audio together with the composition plan and song metadata returned in the same response. Useful when you need to log, display, or post-process plan and metadata alongside the audio. 
$detailed = ElevenLabs::music()->composeDetailed('A bright synth-pop theme.', [
    'model_id'        => 'music_v2',
    'with_timestamps' => true,
]);

echo $detailed->songId;
$detailed->output->save(__DIR__.'/theme.mp3');
composeDetailed() sends an Accept: multipart/mixed header and receives audio and JSON metadata as separate parts in a single response. The output_format option is extracted and sent as a query parameter as with compose(). The default format is 'auto'.
​
prompt
string
required
Text description used to compose the track.
​
options
array
Options sent in the JSON body. Common keys include model_id, music_length_ms, with_timestamps, and output_format.
​
DetailedMusicResult
object
​
output
AudioData
The rendered audio data. Call ->save($path) to write the file.
​
compositionPlan
array
The structured plan that was used to generate the track.
​
songMetadata
array
Metadata about the produced song (title, style tags, and similar fields).
​
songId
string|null
ElevenLabs song identifier returned in the song-id response header, if present.

​
composeDetailedFromPlan()

Identical to composeDetailed() but drives the render from an existing plan rather than a fresh prompt. Accepts either a MusicPlan object or a raw array. 
$detailed = ElevenLabs::music()->composeDetailedFromPlan($plan, [
    'model_id' => 'music_v2',
]);

echo $detailed->songId;
$detailed->output->save(__DIR__.'/theme.mp3');
​
plan
MusicPlan|array
required
A MusicPlan instance or a raw plan array.
​
options
array
Generation options including model_id and output_format.
​
DetailedMusicResult
object
Same structure as composeDetailed() — see above for field descriptions.

​
videoToMusic()

Derive a synchronized music soundtrack from one or more video files. Each video is uploaded as a multipart part; the text options (description, tags, model) are sent alongside them. 
$soundtrack = ElevenLabs::music()->videoToMusic([
    Content::video(__DIR__.'/opening.mp4'),
    Content::video(__DIR__.'/closing.mp4'),
], [
    'description' => 'Cinematic, restrained, then uplifting.',
    'tags'        => ['cinematic', 'orchestral'],
    'model_id'    => 'music_v2',
]);

$soundtrack->output->save(__DIR__.'/soundtrack.mp3');
​
videos
Content|list<Content>
required
A single Content value or a list of Content values created with Content::video(). Each item is sent as a separate videos multipart field.
​
options
array
Additional fields appended to the multipart request. Useful keys include description, tags, model_id, and output_format. The default output_format when omitted is mp3_44100_128.
​
AudioResult
object
​
output
AudioData
The generated soundtrack audio.

​
separateStems()

Separate a mixed audio track into individual stems (e.g. vocals, bass, drums). The result is a ZIP archive containing each stem as a separate audio file. 
$stems = ElevenLabs::music()->separateStems(
    Content::audio(__DIR__.'/song.mp3'),
    ['stem_variation_id' => 'six_stems_v1'],
);

$stems->save(__DIR__.'/stems.zip');
​
audio
Content
required
The source audio file, created with Content::audio().
​
options
array
Options sent alongside the file in the multipart request. The output_format key (default mp3_44100_128) is extracted and sent as a query parameter.
​
stem_variation_id
string
Determines how many stems are produced (e.g. six_stems_v1).
​
sign_with_c2pa
bool
Embed a C2PA provenance manifest in each output stem when true.
​
BinaryData
object
​
data
string
Raw bytes of the returned ZIP archive.
​
mimeType
string
MIME type of the response (typically application/zip).
​
filename
string|null
Suggested filename parsed from the Content-Disposition header, if present.
Call $stems->save($path) to write the ZIP file directly to disk. Throws an AiSdkException if the write fails.

​
upload()

Upload a source audio file for use in composition-plan extraction and inpainting workflows. Returns a MusicUpload with the assigned song ID and any plan or timestamp data the API analysed from the file. 
$upload = ElevenLabs::music()->upload(
    Content::audio(__DIR__.'/source.mp3'),
    [
        'extract_composition_plan' => 'music_v2',
        'with_timestamps'          => true,
    ],
);

echo $upload->songId;

// Optional — only present when the API analysed and returned them
if ($upload->compositionPlan !== null) {
    print_r($upload->compositionPlan);
}

foreach ($upload->wordTimestamps as $ts) {
    echo "{$ts['word']}: {$ts['start']} → {$ts['end']}\n";
}
​
audio
Content
required
The source audio to upload, created with Content::audio().
​
options
array
Additional multipart fields. Common keys:
​
extract_composition_plan
string
Model ID to use when extracting a composition plan from the uploaded file (e.g. music_v2).
​
with_timestamps
bool
When true, the API returns word-level timestamp data.
​
MusicUpload
object
​
songId
string
The ElevenLabs identifier assigned to the uploaded track.
​
compositionPlan
array|null
Extracted composition plan, or null if the API did not return one.
​
wordTimestamps
list
Array of word-timing objects. Each entry is an associative array with at least word, start, and end keys. Empty when timestamps were not requested.

​
Data Classes

​
MusicPlan

Returned by plan(). Wraps the raw plan array so it can be passed directly to composeFromPlan() or composeDetailedFromPlan() without unwrapping it yourself.
PropertyTypeDescription
valuearrayThe raw composition plan from ElevenLabs, including section chunks, styles, and structural metadata.

​
DetailedMusicResult

Returned by composeDetailed() and composeDetailedFromPlan(). Bundles audio and structured metadata from the multipart/mixed response.
PropertyTypeDescription
outputAudioDataRendered audio bytes and MIME type.
compositionPlanarrayThe plan that governed this composition.
songMetadataarrayTitle, style, and other song-level metadata.
songIdstring|nullSong identifier from the song-id response header.
rawMetadataarrayThe complete, unparsed JSON metadata object from the response.

​
MusicUpload

Returned by upload(). Carries the song ID and any analytical data derived from the uploaded file.
PropertyTypeDescription
songIdstringElevenLabs identifier for the uploaded track.
compositionPlanarray|nullExtracted plan, if requested and returned.
wordTimestampslistWord-timing entries, empty when not requested.
rawResponsearrayThe complete, unparsed JSON response from the upload endpoint.

​
Available Models

Model IDDescription
music_v1First-generation ElevenLabs music model.
music_v2Second-generation model with improved structure and plan support.
Pass these values via the model_id option on any music method.

Build docs developers (and LLMs) love

Get started for freeTalk to us