API Reference
ElevenLabs Text-to-Sound
Use the text to sound endpoint to create an asynchronous Task.
01
Overview
Use the text to sound endpoint with the required inputs. Use the returned Task ID to retrieve its state, or provide callback_url for the deliveries documented below.
Quick start
- Create an API key and set it as RUNAPI_API_KEY.
- Send a POST request whose body matches the request schema.
- Store the returned task ID, then poll until a terminal state or handle the callbacks documented below.
Endpoint
- Base URL
https://runapi.ai- API version
v1- Authentication
Authorization: Bearer YOUR_API_TOKEN
02
Supported models
Open a model page for current pricing, rate limits, and commercial-usage details.
03
JSON bodyRequest schema
Send only the documented fields. When supplied, callback_url receives the Task deliveries documented below.
sound-effect-v26 fields
callback_urlstring
Optional
duration_secondsnumber
Optional
loopboolean
Optional
output_formatstring
Optional
Allowed values:
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
prompt_influencenumber
Optional
textstring
Required
04
HTTP 202Create acceptance
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Polling processing
GET /api/v1/elevenlabs/text_to_sound/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Polling completed
GET /api/v1/elevenlabs/text_to_sound/:id
Response schema
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"audios",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"audios": [
{
"url": "https://file.runapi.ai/reference-audio.mp3"
}
],
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed"
}07
HTTP 200Polling failed
GET /api/v1/elevenlabs/text_to_sound/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Customer callback: completed
POST callback_url
Response schema
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"audios"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"audios": [
{
"url": "https://file.runapi.ai/reference-audio.mp3"
}
],
"id": "tsk_reference_demo",
"status": "completed"
}09
HTTP 200Customer callback: failed
POST callback_url
Response schema
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Authentication required"
}11
HTTP 401Errors
GET /api/v1/elevenlabs/text_to_sound/:id
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Authentication required"
}12
HTTP 400Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Human-readable validation summary.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Validation messages keyed by public request field, with an array of human-readable strings for each field.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Response example
JSON
{
"error": "Validation failed",
"errors": {
"text": [
"is required"
]
}
}13
HTTP 402Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Insufficient balance"
}14
HTTP 429Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504Errors
POST /api/v1/elevenlabs/text_to_sound
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "The request timed out"
}19
HTTP 404Errors
GET /api/v1/elevenlabs/text_to_sound/:id
Response schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
Generated Code Samples
Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.
Install
Shell
pip install runapi-elevenlabs
PYTHON
import os
from runapi.elevenlabs import ElevenlabsClient
client = ElevenlabsClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_sound.create(
text="Heavy rain on a tin roof.",
loop=False,
duration_seconds=5,
prompt_influence=0.8,
output_format="mp3_44100_128"
)