ElevenLabs

Access the ElevenLabs API with managed authentication. Generate lifelike speech from text, clone voices, create sound effects, and process audio.

Quick Start

# List available voices
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/elevenlabs/v1/voices')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/elevenlabs/{native-api-path}

Replace {native-api-path} with the actual ElevenLabs API endpoint path. The gateway proxies requests to api.elevenlabs.io and automatically injects your API key.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your ElevenLabs connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=elevenlabs&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'elevenlabs'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "ff2079b1-f40a-43b7-a807-1d5deea29c5b",
    "status": "ACTIVE",
    "creation_time": "2026-02-12T00:50:40.292363Z",
    "last_updated_time": "2026-02-12T00:51:14.547893Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "elevenlabs",
    "metadata": {}
  }
}

Open the returned url in a browser to complete authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple ElevenLabs connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/elevenlabs/v1/voices')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'ff2079b1-f40a-43b7-a807-1d5deea29c5b')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Text-to-Speech

Convert Text to Speech

POST /elevenlabs/v1/text-to-speech/{voice_id}
Content-Type: application/json

{
  "text": "Hello, this is a test of the ElevenLabs API.",
  "model_id": "eleven_multilingual_v2",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75
  }
}

Returns audio data (mp3 by default).

Query parameters:

• output_format - Audio format (e.g., mp3_44100_128, pcm_16000, pcm_22050)

Stream Text to Speech

POST /elevenlabs/v1/text-to-speech/{voice_id}/stream
Content-Type: application/json

{
  "text": "Hello, this is streamed audio.",
  "model_id": "eleven_multilingual_v2"
}

Returns streaming audio data.

Text to Speech with Timestamps

POST /elevenlabs/v1/text-to-speech/{voice_id}/with-timestamps
Content-Type: application/json

{
  "text": "Hello world",
  "model_id": "eleven_multilingual_v2"
}

Returns audio with word-level timestamps.

Voices

List Voices

GET /elevenlabs/v1/voices

Returns all available voices including premade and cloned voices.

Get Voice

GET /elevenlabs/v1/voices/{voice_id}

Returns metadata about a specific voice.

Get Default Voice Settings

GET /elevenlabs/v1/voices/settings/default

Get Voice Settings

GET /elevenlabs/v1/voices/{voice_id}/settings

Create Voice Clone

POST /elevenlabs/v1/voices/add
Content-Type: multipart/form-data

name: My Cloned Voice
files: [audio_sample.mp3]
description: A custom voice clone
remove_background_noise: false

Edit Voice

PATCH /elevenlabs/v1/voices/{voice_id}/edit
Content-Type: multipart/form-data

name: Updated Voice Name
description: Updated description

Delete Voice

DELETE /elevenlabs/v1/voices/{voice_id}

Models

List Models

GET /elevenlabs/v1/models

Returns available models:

• eleven_multilingual_v2 - Latest multilingual model
• eleven_turbo_v2_5 - Low-latency model
• eleven_monolingual_v1 - Legacy English model (deprecated)

User

Get User Info

GET /elevenlabs/v1/user

Get Subscription Info

GET /elevenlabs/v1/user/subscription

Returns subscription details including character limits and usage.

History

List History Items

GET /elevenlabs/v1/history?page_size=100

Query parameters:

• page_size - Number of items per page (default: 100, max: 1000)
• start_after_history_item_id - Cursor for pagination
• voice_id - Filter by voice

Get History Item

GET /elevenlabs/v1/history/{history_item_id}

Get Audio from History

GET /elevenlabs/v1/history/{history_item_id}/audio

Returns the audio file for a history item.

Delete History Item

DELETE /elevenlabs/v1/history/{history_item_id}

Download History Items

POST /elevenlabs/v1/history/download
Content-Type: application/json

{
  "history_item_ids": ["id1", "id2", "id3"]
}

Returns a zip file with the requested audio files.

Sound Effects

Generate Sound Effect

POST /elevenlabs/v1/sound-generation
Content-Type: application/json

{
  "text": "A thunderstorm with heavy rain and distant thunder",
  "duration_seconds": 10.0
}

Query parameters:

• output_format - Audio format (e.g., mp3_44100_128)

Audio Isolation

Remove Background Noise

POST /elevenlabs/v1/audio-isolation
Content-Type: multipart/form-data

audio: [audio_file.mp3]

Returns cleaned audio with background noise removed.

Stream Audio Isolation

POST /elevenlabs/v1/audio-isolation/stream
Content-Type: multipart/form-data

audio: [audio_file.mp3]

Speech-to-Text

Transcribe Audio

POST /elevenlabs/v1/speech-to-text
Content-Type: multipart/form-data

audio: [audio_file.mp3]
model_id: scribe_v1

Returns transcription with optional word-level timestamps.

Speech-to-Speech (Voice Changer)

Convert Voice

POST /elevenlabs/v1/speech-to-speech/{voice_id}
Content-Type: multipart/form-data

audio: [source_audio.mp3]
model_id: eleven_multilingual_sts_v2

Transforms audio to use a different voice while preserving intonation.

Projects

List Projects

GET /elevenlabs/v1/projects

Get Project

GET /elevenlabs/v1/projects/{project_id}

Create Project

POST /elevenlabs/v1/projects
Content-Type: application/json

{
  "name": "My Audiobook Project",
  "default_title_voice_id": "voice_id",
  "default_paragraph_voice_id": "voice_id"
}

Pronunciation Dictionaries

List Pronunciation Dictionaries

GET /elevenlabs/v1/pronunciation-dictionaries

Create Pronunciation Dictionary

POST /elevenlabs/v1/pronunciation-dictionaries/add-from-file
Content-Type: multipart/form-data

name: My Dictionary
file: [lexicon.pls]

Response Headers

ElevenLabs API responses include useful headers:

• x-character-count - Characters used in the request
• request-id - Unique request identifier

Pagination

History and other list endpoints use cursor-based pagination:

GET /elevenlabs/v1/history?page_size=100&start_after_history_item_id=last_item_id

Code Examples

JavaScript - Text to Speech

const response = await fetch(
  'https://gateway.maton.ai/elevenlabs/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Hello world!',
      model_id: 'eleven_multilingual_v2'
    })
  }
);
const audioBuffer = await response.arrayBuffer();

Python - Text to Speech

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/elevenlabs/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'text': 'Hello world!',
        'model_id': 'eleven_multilingual_v2'
    }
)
audio_data = response.content
with open('output.mp3', 'wb') as f:
    f.write(audio_data)

Python - List Voices

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/elevenlabs/v1/voices',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
voices = response.json()
for voice in voices['voices']:
    print(f"{voice['name']}: {voice['voice_id']}")

Notes

• Text-to-Speech is billed per character
• Sound Effects are billed per generation
• Speech-to-Text is billed per audio minute
• Audio output format can be specified as codec_sample_rate_bitrate (e.g., mp3_44100_128)
• Models available: eleven_multilingual_v2 (recommended), eleven_turbo_v2_5 (low latency)
• Voice IDs can be found using the List Voices endpoint
• Maximum text length varies by model
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq, environment variables may not expand correctly. Use Python examples instead.

Error Handling

Status	Meaning
400	Missing ElevenLabs connection or invalid request
401	Invalid or missing Maton API key
403	Insufficient permissions or quota exceeded
422	Invalid parameters
429	Rate limited
4xx/5xx	Passthrough error from ElevenLabs API

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with elevenlabs. For example:

• Correct: https://gateway.maton.ai/elevenlabs/v1/voices
• Incorrect: https://gateway.maton.ai/v1/voices

Resources

• ElevenLabs API Documentation
• ElevenLabs Developer Portal
• ElevenLabs Models Overview
• Maton Community
• Maton Support