Voces disponibles

Las voces no tienen endpoint propio: viven en el catálogo, junto con idiomas, tonos, estilos de mensaje, etiquetas y eventos de webhook. Se consultan filtrando por tipo en GET /v1/catalogs/items.

Requiere permiso catalogs:read y el header X-Workspace-Id. El catálogo mezcla los ítems globales con los propios del workspace.

Tipos de ítem

El campo type acepta un conjunto cerrado de valores:

`type`	Qué contiene
`voice`	Voces de los proveedores configurados
`language`	Idiomas y variantes regionales
`tone_style`	Tonos de conversación
`message_style`	Estilos de redacción del mensaje
`tag`	Etiquetas de clasificación
`webhook_event`	Eventos a los que un webhook se puede suscribir

Listar las voces

El filtro se escribe con la gramática del query builder: eq(type,"voice").

curl --request GET \
  --url "$API_BASE_URL/v1/catalogs/items?filter=eq(type,%22voice%22)&limit=50" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID"

const response = await fetch(
  `${process.env.API_BASE_URL}/v1/catalogs/items?` +
    new URLSearchParams({
      filter: 'eq(type,"voice")',
      limit: '50',
    }),
  {
    headers: {
      'X-API-Key': process.env.API_KEY!,
      'X-Workspace-Id': process.env.WORKSPACE_ID!,
    },
  },
);

const { data, meta } = await response.json();
console.log(meta.total, data[0]?.name);

Respuesta

{
  "data": [
    {
      "id": "3f7c1d02-9b44-4a1e-8f30-5b6e2c9a7d11",
      "type": "voice",
      "systemIdentifier": "elevenlabs.rachel",
      "scope": "global",
      "workspaceId": null,
      "name": "Rachel (ElevenLabs)",
      "description": "Voz femenina multilingüe con acento estadounidense.",
      "isActive": true,
      "metadata": {
        "provider": "elevenlabs",
        "voiceId": "21m00Tcm4TlvDq8ikWAM",
        "gender": "female"
      },
      "createdAt": "2026-01-08T12:00:00.000Z",
      "updatedAt": "2026-01-08T12:00:00.000Z",
      "links": {
        "self": "/v1/catalogs/items/3f7c1d02-9b44-4a1e-8f30-5b6e2c9a7d11",
        "catalog": "/v1/catalogs/items"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50,
    "hasNext": false,
    "hasPrevious": false,
    "sort": ["createdAt"],
    "appliedFilters": { "type": "voice" }
  }
}

Los atributos que varían por proveedor —voiceId, género, acento— viajan en metadata, así que conviene leerlos de ahí y no asumir columnas fijas.

Combinar filtros

filter=and(eq(type,"voice"),eq(isActive,true))

filter=and(eq(type,"voice"),eq(scope,"workspace"))

filter=eq(type,"voice")&q=rachel

Los parámetros include y fields no están soportados por el query builder; las respuestas siempre traen el objeto completo. Para paginar se usan page (desde 1) y limit (máximo 100), y para ordenar sort, con - como prefijo para descendente.

Con el SDK de TypeScript

El SDK trae un atajo que hace este filtrado y normaliza cada ítem a una forma de voz, así que no hay que armar el filter a mano:

const voices = await client.voices.list({
  gender: 'female',
  locale: 'es-MX',
  limit: 20,
});

console.log(voices.meta.total, voices.data[0]?.name);

Por debajo llama al mismo GET /v1/catalogs/items.

Usar una voz en un agente

El id del ítem de catálogo es lo que se envía al crear o actualizar la versión del agente. La lista completa de campos está en la referencia de Agent Versions.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

Tipos de ítem

Listar las voces

Respuesta

Combinar filtros

Con el SDK de TypeScript

Usar una voz en un agente

​Tipos de ítem

​Listar las voces

​Respuesta

​Combinar filtros

​Con el SDK de TypeScript

​Usar una voz en un agente

Tipos de ítem

Listar las voces

Respuesta

Combinar filtros

Con el SDK de TypeScript

Usar una voz en un agente