Elevenlabs Music V2.5
elevenlabs/music-v2.5
Pricing
elevenlabs/music-v2.5 per minute (rounded up)
| Unit Price | $0.860 |
|---|
Introduction coming soon
A detailed guide for this model is being prepared. Pricing, parameters and the API docs below are already available.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.
Idempotency-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.
Body
modelstringRequiredCurrent fixed value: elevenlabs/music-v2.5
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for elevenlabs/music-v2.5 and route default — see the parameter table below.
seedintegerOptionalmin 0max 2147483647Composition plan mode only. Same seed and parameters give more consistent, not identical, results.
modelstringOptionalDefault: "elevenlabs/music-v2.5"Model name
elevenlabs/music-v2.5promptstringOptionalminLength 1maxLength 4100pattern \SDescribe genre, mood, instruments, vocals, structure and lyrics. Supply a prompt or a composition plan, not both.
output_formatstringOptionalDefault: "mp3_48000_192"codec_samplerate_bitrate, for example mp3_48000_192.
mp3_22050_32mp3_24000_48mp3_44100_32mp3_44100_64mp3_44100_96mp3_44100_128mp3_44100_192mp3_48000_128Show all (17)
mp3_48000_192mp3_48000_240mp3_48000_320pcm_8000pcm_16000pcm_22050pcm_24000pcm_32000pcm_44100pcm_48000ulaw_8000alaw_8000opus_48000_32opus_48000_64opus_48000_96opus_48000_128opus_48000_192music_length_msintegerOptionalDefault: 60000min 3000max 600000Length of the generated music in milliseconds, 3,000 to 600,000. Prompt mode only. Defaults to 60,000 (1 minute).
composition_planobjectOptional
Chunk-by-chunk plan. 1 to 30 chunks, total duration 3,000 to 600,000 ms. Supply a composition plan or a prompt, not both.
chunksarrayRequiredminItems 1maxItems 30
Array [ object ]
Array items
textstringRequiredminLength 1Optional [Section name] followed by lyric lines; inline directions in {curly braces}. Up to 30 lines of 200 characters.
duration_msintegerRequiredmin 3000max 120000audio_referenceobjectOptional
end_msintegerOptionalDefaults to 30,000 ms after start_ms or the end of the clip. The window is at most 30,000 ms.
start_msintegerOptionalDefault: 0min 0strengthstringOptionallowmediumhighxhighaudio_urlstringRequiredAudio clip whose style conditions this chunk. The reference on the first chunk influences the whole song.
negative_stylesarrayOptionalArray [ string ]
positive_stylesarrayRequiredStyles and musical directions for this chunk, English works best. The first chunk sets the overall tone.
Array [ string ]
context_adherencestringOptionallowmediumhighforce_instrumentalbooleanOptionalDefault: falseGuarantee an instrumental result without vocals. Prompt mode only.
callbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.
urlstringRequiredRequired when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.
whenstringOptionalDefault: "final"Only final is supported today — notified on both success and fail.
finalstoragestringOptionalDefault: "temp"Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.
temppersistentRequest examples
# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "elevenlabs/music-v2.5",
"input": {
"model": "elevenlabs/music-v2.5",
"output_format": "mp3_48000_192",
"music_length_ms": 60000,
"force_instrumental": false
}
}'const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "elevenlabs/music-v2.5",
input: {
"model": "elevenlabs/music-v2.5",
"output_format": "mp3_48000_192",
"music_length_ms": 60000,
"force_instrumental": false
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "elevenlabs/music-v2.5",
"input": {
"model": "elevenlabs/music-v2.5",
"output_format": "mp3_48000_192",
"music_length_ms": 60000,
"force_instrumental": false
}
},
)
print(res.json()) # { code, message, data: { taskId } }200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
}400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
}Get task detail
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
queued Queued, not started yet.
handling Being processed.
archiving Processing finished, artifacts being prepared.
success Terminal: completed, artifacts available (output returned).
fail Terminal: failed (error returned).
After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix seconds when the task reached a terminal state; fixed to 0 while not terminal.
outputarrayOptional
Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).
Array [ object ]
Array items
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError description.
Response examples
Success
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
}Processing (non-terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
}Failed
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
}
