Guía de inicio rápido de Speech Engine

Crea una clave de API

Crea una clave de API en el panel aquí, que usarás para acceder a la API de forma segura.

Guarda la clave como un secreto gestionado y pásala a los SDK como variable de entorno mediante un archivo .env o directamente en la configuración de tu aplicación, según prefieras.

ELEVENLABS_API_KEY=<your_api_key_here>

Instala las dependencias

pip install elevenlabs openai python-dotenv

Expón el servidor

Speech Engine necesita una URL accesible públicamente. Usa ngrok para exponer tu servidor local. El servidor aún no está creado, pero ngrok debe estar ejecutándose primero para que tengas la URL para el siguiente paso.

ngrok http 3001

Copia la URL de reenvío (por ejemplo, https://abc123.ngrok.io).

Crea una instancia de Speech Engine

Usa el SDK para crear una instancia de Speech Engine y pasa tu URL de ngrok con la ruta /ws añadida como URL de WebSocket.

import asyncio
from dotenv import load_dotenv
from elevenlabs import AsyncElevenLabs
load_dotenv()
elevenlabs = AsyncElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
async def main():
    engine = await elevenlabs.speech_engine.create(
        name="My Speech Engine",
        speech_engine={
            # Note we use the wss protocol instead of https
            "ws_url": "wss://abc123.ngrok.io/ws",
        },
    )
    print(f"Speech Engine ID: {engine.engine_id}")
if __name__ == "__main__":
    asyncio.run(main())

Ejecuta este script y copia el ID de Speech Engine (por ejemplo, seng_8k3m9xr4hjnfg983brhmhkd98n6) para el siguiente paso.

Crea el servidor

Crea un archivo llamado server.py o server.mts con el siguiente contenido. Esto configura un servidor, conecta Speech Engine en la ruta /ws y usa OpenAI para generar respuestas.

import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
load_dotenv()
# Replace with your Speech Engine ID from step 4
SPEECH_ENGINE_ID = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
openai = AsyncOpenAI(
  api_key=os.getenv("OPENAI_API_KEY"),
)
elevenlabs = AsyncElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def on_init(conversation_id, session):
    print(f"Session started: {conversation_id}")
async def on_transcript(transcript, session):
    stream = await openai.responses.create(
        model="gpt-4o",
        instructions="You are a helpful voice assistant. Keep responses concise and conversational.",
        input=[
            {"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
            for m in transcript
        ],
        stream=True,
    )
    await session.send_response(stream)
def on_close(session):
    print(f"Session ended: {session.conversation_id}")
def on_error(err, session):
    print(f"Error: {err}")
async def main():
    engine = await elevenlabs.speech_engine.get(SPEECH_ENGINE_ID)
    await engine.serve(
        port=3001,
        path="/ws",
        debug=True,
        on_init=on_init,
        on_transcript=on_transcript,
        on_close=on_close,
        on_error=on_error,
    )
if __name__ == "__main__":
    asyncio.run(main())

El callback onTranscript / on_transcript recibe el historial completo de la conversación y la sesión actual. El SDK de TypeScript también proporciona un AbortSignal que se activa si el usuario interrumpe durante una respuesta. Pasar signal a la llamada de OpenAI cancela automáticamente la solicitud al LLM cuando hay una interrupción.

sendResponse() / send_response() acepta una cadena, un iterable asíncrono o un stream de OpenAI, Anthropic o Google Gemini. El SDK extrae automáticamente el contenido de texto.

Inicia el servidor

python server.py

Instala el SDK de cliente

npm install @elevenlabs/react

Crea una ruta de token

Añade una ruta en el servidor que genere un token de conversación. Así mantienes tu clave de API fuera del navegador y usas WebRTC para obtener la mejor calidad de audio.

import os
from dotenv import load_dotenv
from flask import Flask, jsonify
from elevenlabs import ElevenLabs
load_dotenv()
app = Flask(__name__)
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
@app.route("/api/token")
def get_token():
    # Replace with your Speech Engine ID from step 4 of the server setup
    speech_engine_id = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
    response = elevenlabs.conversational_ai.conversations.get_webrtc_token(
        agent_id=speech_engine_id,
    )
    return jsonify(token=response.token)
if __name__ == "__main__":
    app.run(port=3002)

Crea la interfaz de conversación

Obtén el token de conversación de tu servidor y úsalo para iniciar una sesión.

import { useConversation } from "@elevenlabs/react";
import { useCallback } from "react";
async function getToken(): Promise<string> {
  const response = await fetch("/api/token");
  if (!response.ok) {
    throw Error("Failed to get conversation token");
  }
  const data = await response.json();
  return data.token;
}
export default function App() {
  const conversation = useConversation({
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Disconnected"),
    onError: (error: Error) => console.error("Error:", error),
  });
  const startConversation = useCallback(async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    const token = await getToken();
    await conversation.startSession({ conversationToken: token });
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div>
      <p>Status: {conversation.status}</p>
      <button onClick={startConversation} disabled={conversation.status === "connected"}>
        Start conversation
      </button>
      <button onClick={stopConversation} disabled={conversation.status !== "connected"}>
        End conversation
      </button>
    </div>
  );
}

Pruébalo

Asegúrate de que haya tres procesos en ejecución:

1. ngrok: reenvío al puerto 3001
2. Tu servidor de Speech Engine: python server.py o npx tsx server.mts
3. El servidor de tokens: npx tsx token-server.mts o python token_server.py

Abre tu aplicación cliente en el navegador y haz clic en Iniciar conversación. Concede acceso al micrófono cuando se te solicite y, después, habla. Deberías escuchar la respuesta del agente por los altavoces.

Si tienes debug: true activado en el servidor, verás en la consola las transcripciones entrantes y las respuestas salientes.

Para permitir que el agente hable primero, debemos actualizar el recurso de Speech Engine para permitir configurarlo desde el cliente.

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    overrides={
      "first_message": True,
    },
)

A continuación, configuramos el primer mensaje en el SDK de cliente.

conversation.startSession({
  conversationToken: token,
  overrides: {
    agent: {
      firstMessage: "Hello! How can I help you today?",
    },
  },
});