Skip to content

Commit 8739a6a

Browse files
ojaragodwinojaragodwin
authored
Merge pull request #7 from iblai/external-service-proxy-doc
add external service proxy documentation with example
2 parents b41cc7f + 76efeae commit 8739a6a

5 files changed

Lines changed: 1855 additions & 0 deletions

File tree

‎developer/externalserviceproxy/elevenlabs.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# ElevenLabs Integration
2+
3+
## Overview
4+
5+
ElevenLabs provides advanced text-to-speech (TTS) capabilities with natural-sounding voices. The External Service Proxy API allows you to integrate ElevenLabs TTS functionality into your application.
6+
7+
**Developer**
8+
9+
---
10+
11+
## Prerequisites
12+
13+
- ElevenLabs API credentials configured for your organization
14+
- See [Credential Setup](errors.md#setting-up-credentials) for configuration details
15+
- Valid API key or token for authentication
16+
17+
---
18+
19+
## List Voices
20+
21+
Get all available ElevenLabs voices.
22+
23+
**Endpoint:**
24+
```
25+
POST /api/ai-proxy/orgs/{org}/services/elevenlabs/list-voices/
26+
```
27+
28+
**Request:**
29+
```json
30+
{}
31+
```
32+
33+
**Response:**
34+
```json
35+
{
36+
"voices": [
37+
{
38+
"voice_id": "21m00Tcm4TlvDq8ikWAM",
39+
"name": "Rachel",
40+
"category": "premade",
41+
"labels": {
42+
"accent": "american",
43+
"gender": "female"
44+
}
45+
}
46+
]
47+
}
48+
```
49+
50+
**Frontend Example:**
51+
```javascript
52+
async function listVoices(org, apiKey) {
53+
const response = await fetch(
54+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/list-voices/`,
55+
{
56+
method: 'POST',
57+
headers: {
58+
'Authorization': `Api-Key ${apiKey}`,
59+
'Content-Type': 'application/json',
60+
},
61+
body: JSON.stringify({})
62+
}
63+
);
64+
65+
const data = await response.json();
66+
return data.voices;
67+
}
68+
```
69+
70+
---
71+
72+
## List Models
73+
74+
Get all available TTS models.
75+
76+
**Endpoint:**
77+
```
78+
POST /api/ai-proxy/orgs/{org}/services/elevenlabs/list-models/
79+
```
80+
81+
**Request:**
82+
```json
83+
{}
84+
```
85+
86+
**Response:**
87+
```json
88+
[
89+
{
90+
"model_id": "eleven_multilingual_v2",
91+
"name": "Eleven Multilingual v2",
92+
"description": "Our most advanced model..."
93+
}
94+
]
95+
```
96+
97+
**Frontend Example:**
98+
```javascript
99+
async function listModels(org, apiKey) {
100+
const response = await fetch(
101+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/list-models/`,
102+
{
103+
method: 'POST',
104+
headers: {
105+
'Authorization': `Api-Key ${apiKey}`,
106+
'Content-Type': 'application/json',
107+
},
108+
body: JSON.stringify({})
109+
}
110+
);
111+
112+
return await response.json();
113+
}
114+
```
115+
116+
---
117+
118+
## Text-to-Speech
119+
120+
Convert text to speech audio.
121+
122+
**Endpoint:**
123+
```
124+
POST /api/ai-proxy/orgs/{org}/services/elevenlabs/tts/
125+
```
126+
127+
**Path Template:** `/v1/text-to-speech/{voice_id}`
128+
129+
**Required Path Parameters:**
130+
- `voice_id` - The ID of the voice to use (get from List Voices endpoint)
131+
132+
**Request:**
133+
```json
134+
{
135+
"path_params": {
136+
"voice_id": "21m00Tcm4TlvDq8ikWAM"
137+
},
138+
"body": {
139+
"text": "Hello, this is a test.",
140+
"model_id": "eleven_multilingual_v2",
141+
"voice_settings": {
142+
"stability": 0.5,
143+
"similarity_boost": 0.5
144+
}
145+
}
146+
}
147+
```
148+
149+
**Request Body Parameters:**
150+
151+
| Parameter | Type | Required | Description |
152+
|-----------|------|----------|-------------|
153+
| `text` | string | Yes | The text to convert to speech |
154+
| `model_id` | string | Yes | The TTS model to use |
155+
| `voice_settings` | object | No | Voice customization settings |
156+
| `voice_settings.stability` | number | No | Voice stability (0.0 - 1.0) |
157+
| `voice_settings.similarity_boost` | number | No | Voice similarity boost (0.0 - 1.0) |
158+
159+
**Response:**
160+
- Content-Type: `audio/mpeg`
161+
- Body: Binary audio data (MP3)
162+
163+
**Frontend Example:**
164+
```javascript
165+
async function textToSpeech(org, apiKey, text, voiceId) {
166+
const response = await fetch(
167+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/tts/`,
168+
{
169+
method: 'POST',
170+
headers: {
171+
'Authorization': `Api-Key ${apiKey}`,
172+
'Content-Type': 'application/json',
173+
},
174+
body: JSON.stringify({
175+
path_params: { voice_id: voiceId },
176+
body: {
177+
text: text,
178+
model_id: 'eleven_multilingual_v2',
179+
voice_settings: {
180+
stability: 0.5,
181+
similarity_boost: 0.5
182+
}
183+
}
184+
})
185+
}
186+
);
187+
188+
if (response.ok) {
189+
const audioBlob = await response.blob();
190+
const audioUrl = URL.createObjectURL(audioBlob);
191+
const audio = new Audio(audioUrl);
192+
audio.play();
193+
return audioUrl;
194+
} else {
195+
const error = await response.json();
196+
throw new Error(error.detail || 'TTS request failed');
197+
}
198+
}
199+
```
200+
201+
---
202+
203+
## Complete Workflow Example
204+
205+
This example demonstrates a complete workflow: discovering voices, selecting one, and generating speech.
206+
207+
```javascript
208+
async function elevenLabsWorkflow(org, apiKey) {
209+
// Step 1: Get available voices
210+
const voicesResponse = await fetch(
211+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/list-voices/`,
212+
{
213+
method: 'POST',
214+
headers: {
215+
'Authorization': `Api-Key ${apiKey}`,
216+
'Content-Type': 'application/json',
217+
},
218+
body: JSON.stringify({})
219+
}
220+
);
221+
const voicesData = await voicesResponse.json();
222+
const voices = voicesData.voices;
223+
224+
console.log('Available voices:', voices.map(v => v.name));
225+
226+
// Step 2: Get available models
227+
const modelsResponse = await fetch(
228+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/list-models/`,
229+
{
230+
method: 'POST',
231+
headers: {
232+
'Authorization': `Api-Key ${apiKey}`,
233+
'Content-Type': 'application/json',
234+
},
235+
body: JSON.stringify({})
236+
}
237+
);
238+
const models = await modelsResponse.json();
239+
240+
console.log('Available models:', models.map(m => m.model_id));
241+
242+
// Step 3: Select a voice and model
243+
const selectedVoice = voices[0];
244+
const selectedModel = models[0];
245+
246+
// Step 4: Generate speech
247+
const ttsResponse = await fetch(
248+
`/api/ai-proxy/orgs/${org}/services/elevenlabs/tts/`,
249+
{
250+
method: 'POST',
251+
headers: {
252+
'Authorization': `Api-Key ${apiKey}`,
253+
'Content-Type': 'application/json',
254+
},
255+
body: JSON.stringify({
256+
path_params: { voice_id: selectedVoice.voice_id },
257+
body: {
258+
text: 'Hello! This is a demonstration of the ElevenLabs text-to-speech API.',
259+
model_id: selectedModel.model_id,
260+
voice_settings: {
261+
stability: 0.5,
262+
similarity_boost: 0.5
263+
}
264+
}
265+
})
266+
}
267+
);
268+
269+
if (ttsResponse.ok) {
270+
const audioBlob = await ttsResponse.blob();
271+
const audioUrl = URL.createObjectURL(audioBlob);
272+
273+
// Play the audio
274+
const audio = new Audio(audioUrl);
275+
audio.play();
276+
277+
console.log('Audio generated successfully!');
278+
return audioUrl;
279+
} else {
280+
const error = await ttsResponse.json();
281+
console.error('TTS failed:', error);
282+
throw new Error(error.detail || 'TTS request failed');
283+
}
284+
}
285+
286+
// Usage
287+
elevenLabsWorkflow('my-org', 'my-api-key')
288+
.then(audioUrl => console.log('Audio URL:', audioUrl))
289+
.catch(error => console.error('Workflow failed:', error));
290+
```
291+
292+
---
293+
294+
## Related Pages
295+
296+
- [Overview](overview.md) - Authentication and service discovery
297+
- [Integration Guide](integration.md) - Path templates and dynamic client
298+
- [HeyGen Integration](heygen.md) - Video generation endpoints
299+
- [Error Handling](errors.md) - Error responses and credential setup

0 commit comments

Comments
 (0)