Início

Introdução Autenticação

Endpoints

Text-to-Speech Obter Áudio Listar Vozes Estatísticas

Exemplos

Exemplos de Uso

Documentação da API

Bem-vindo à documentação do ElevenLabs Cache. Esta API serve como intermediário para o ElevenLabs com sistema inteligente de cache para economizar tokens.

💡 Dica: Todas as requisições (exceto /api/health) requerem uma API Key válida.

Autenticação

Para usar a API, você precisa de uma API Key. Inclua-a em suas requisições de uma das seguintes formas:

Header HTTP

X-API-Key: sua_api_key_aqui

Query Parameter

?api_key=sua_api_key_aqui
⚠️ Importante: Obtenha sua API Key no Painel Admin

POST /api/tts

Converte texto em áudio usando uma voz específica. O sistema verifica automaticamente se o áudio já está em cache e retorna uma URL para o arquivo MP3.

Request Body

{
  "text": "Texto para converter em áudio",
  "voice_id": "ID_DA_VOZ",
  "model_id": "eleven_turbo_v2_5"
}

Response (JSON)

{
  "success": true,
  "audio_url": "http://seu-dominio.com/api/audio/abc123...",
  "format": "mp3",
  "cache": "HIT",  // ou "MISS"
  "cache_key": "abc123...",
  "access_count": 5,  // apenas em cache HIT
  "file_size": 45678
}
💡 Nova Funcionalidade: A API agora retorna uma URL para o arquivo de áudio MP3. Use esta URL para fazer download ou reproduzir o áudio. A URL é pública e não requer autenticação.

Exemplo com cURL

curl -X POST http://localhost:3000/api/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{"text": "Olá, mundo!", "voice_id": "2EiwWnXFnvU5JabPnv8n"}'

Baixar o Áudio

Após obter a URL do áudio, você pode baixá-lo diretamente:

curl -o audio.mp3 "http://localhost:3000/api/audio/abc123..."

Teste Interativo

GET /api/audio/:cacheKey

Serve o arquivo de áudio MP3 diretamente. Esta é uma rota pública que não requer autenticação.

Parâmetros

  • cacheKey (URL): Chave única do cache retornada pelo endpoint /api/tts

Exemplo

curl -o audio.mp3 http://localhost:3000/api/audio/abc123...def456
💡 Dica: Esta URL pode ser usada diretamente em tags <audio> HTML ou players de áudio.

GET /api/voices

Lista todas as vozes disponíveis na sua conta ElevenLabs.

Exemplo com cURL

curl -H "X-API-Key: sua_api_key_aqui" \
  http://localhost:3000/api/voices

Response

{
  "success": true,
  "count": 28,
  "voices": [
    {
      "voice_id": "2EiwWnXFnvU5JabPnv8n",
      "name": "Clyde",
      "labels": {
        "gender": "male",
        "accent": "american"
      }
    }
  ]
}

GET /api/cache/stats

Retorna estatísticas detalhadas do cache.

Exemplo com cURL

curl -H "X-API-Key: sua_api_key_aqui" \
  http://localhost:3000/api/cache/stats

Exemplos Completos

JavaScript / Node.js

const API_URL = 'http://localhost:3000';
const API_KEY = 'sua_api_key_aqui';

// Listar vozes
const voices = await fetch(`${API_URL}/api/voices`, {
  headers: { 'X-API-Key': API_KEY }
}).then(r => r.json());

// Gerar áudio (retorna URL)
const result = await fetch(`${API_URL}/api/tts`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    text: 'Olá, mundo!',
    voice_id: voices.voices[0].voice_id
  })
}).then(r => r.json());

console.log('Cache:', result.cache);
console.log('Audio URL:', result.audio_url);

// Baixar o áudio usando a URL
const audioResponse = await fetch(result.audio_url);
const audioBlob = await audioResponse.blob();

// Ou usar diretamente em um elemento de áudio
// const audio = new Audio(result.audio_url);
// audio.play();

Python

import requests

API_URL = 'http://localhost:3000'
API_KEY = 'sua_api_key_aqui'

# Listar vozes
voices = requests.get(
    f'{API_URL}/api/voices',
    headers={'X-API-Key': API_KEY}
).json()

# Gerar áudio (retorna URL)
result = requests.post(
    f'{API_URL}/api/tts',
    headers={'X-API-Key': API_KEY},
    json={
        'text': 'Olá, mundo!',
        'voice_id': voices['voices'][0]['voice_id']
    }
).json()

print(f"Cache: {result['cache']}")
print(f"Audio URL: {result['audio_url']}")

# Baixar o áudio usando a URL
audio_response = requests.get(result['audio_url'])

with open('audio.mp3', 'wb') as f:
    f.write(audio_response.content)