EN

API HTTP · v1

API de voces y audio

De tu primera solicitud a una integración completa. Crea voces, genera audio y usa los caracteres de tu plan.

Crear una API keyDescargar OpenAPI

La API está deshabilitada en este entorno. La referencia es pública; las solicitudes reales todavía no están disponibles.

Inicio rápido

Inicio rápido

1. Inicia sesión y abre Cuenta → Desarrolladores → API. Crea una clave con voices:read, speech:generate, jobs:read y audio:read. Guarda el secreto en VOCLONER_API_KEY en tu servidor.

2. Consulta GET /voices y elige un identificador autorizado. Envía POST /speech con voice_id, text, format y una Idempotency-Key propia y estable.

3. Guarda el id del trabajo y consulta GET /jobs/{id}. Cuando finalice, descarga el recurso con GET /assets/{asset_id}/content, enviando la misma cabecera Authorization. En los ejemplos descargables tienes el flujo completo.

POST /speech

curl --request POST 'https://api.vocloner.org/v1/speech' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"voice_id":"c816ce5b-22f5-4ed2-91a9-90e79b874a24","text":"Hola, esta es mi primera generación con Vocloner.","format":"mp3"}'

Autenticación y permisos

Envía Authorization: Bearer vcl_api_... en cada solicitud. Las claves REST y MCP son credenciales distintas. No envíes secretos en URLs, repositorios ni aplicaciones distribuidas.

Cada clave tiene permisos explícitos, vencimiento y presupuesto opcional. La clave no permite administrar la cuenta ni emitir nuevas claves. Revoca una clave comprometida desde el panel.

Para rotar, crea la sucesora, actualiza tus servidores y revoca la anterior. La rotación no revoca automáticamente la clave existente.

Consultar un trabajo requiere jobs:read y el permiso de su operación original. Cancelarlo exige además jobs:cancel. Usar archivos exige files:write. Elige estos permisos al crear la clave.

Clonación, diseño y consentimiento

Para clonar, prepara un archivo con purpose: clone, súbelo y confírmalo. POST /voices exige consent_ownership: true. Si se requiere un reto, obtén la frase en /consent-challenges, grábala y sube ese audio con purpose: consent.

Las nuevas voces son privadas. Para solicitar publicación, confirma consent_public_use: true. La voz solo será pública cuando cumpla la revisión y moderación requeridas. Reporta uso sin autorización con /reports.

El diseño devuelve candidatas temporales. Consulta el lote y guarda una candidata mediante su candidate_id antes de su vencimiento. Guardar requiere espacio para una voz y no vuelve a cobrar el diseño.

Texto, emociones y diálogos

POST /speech acepta MP3 o WAV y hasta 12.000 caracteres de texto; el límite efectivo por solicitud depende del plan. Las etiquetas expresivas compatibles, como [excited] y [whispering], conservan las reglas de facturación de la web.

Los diálogos admiten entre dos y diez intervenciones, voces autorizadas y pausas de 0 a 3.000 ms. La función debe estar habilitada en tu plan. Cada intervención aplica los límites vigentes.

El audio generado se procesa y verifica antes de estar disponible. No se entregan bytes sin la marca forense. Un fallo de procesamiento puede impedir la entrega aunque el proveedor haya respondido.

Archivos, herramientas y descargas

POST /files devuelve instrucciones de subida temporal al Storage privado. Sube el archivo usando esas instrucciones y confirma con /files/{id}/complete. Un archivo pendiente no puede utilizarse.

El servidor verifica formato, tamaño real, duración y hash. Los límites dependen del propósito y de la operación; consulta /capabilities. Los archivos temporales tienen vencimiento.

Las herramientas aceptan exactamente file_id o generation_id. Consulta las operaciones y opciones habilitadas antes de llamar a /audio-tools/{operation}. Los derivados de audio generado conservan su procedencia.

GET /assets/{id}/content exige autorización en cada descarga. Consulta /generations para historial. Los recursos ajenos responden 404 y los trabajos activos pueden impedir eliminar un archivo.

Límites de subida: clonación 20 MiB y 5–270 segundos; herramientas remotas 20 MiB y hasta 20 minutos; herramientas locales 25 MiB y hasta 15 minutos; consentimiento 5 MiB. La duración debe poder verificarse. La respuesta de capabilities es la referencia del entorno.

Trabajos, reintentos e idempotencia

Las operaciones largas devuelven 202 con id, status, status_url, result y usage. Los estados son queued, running, reconciling, completed, failed y canceled. La reconciliación resuelve un efecto externo cuyo resultado todavía no se confirmó.

Usa Idempotency-Key en operaciones de creación y actualización. Reutiliza la misma clave y el mismo contenido después de un timeout. Cambiar el contenido con la misma clave devuelve 409. La retención de idempotencia es de treinta días.

Respeta Retry-After al consultar trabajos o recibir 429/503. Un POST con Prefer: wait=20 puede responder 200 o 202; ambos usan el recurso trabajo. Nunca generes otro trabajo solo porque el primero tardó.

Cancelar en cola es inmediato. Si el trabajo comenzó, la cancelación es una solicitud: espera su estado final y revisa usage antes de asumir que no hubo consumo.

La colección Postman conserva una Idempotency-Key distinta por operación. Al reintentar, no borres su variable. Para iniciar una operación nueva, vacía la variable idempotency_<operationId> correspondiente.

Caracteres, límites y liquidación

La API, la web y MCP comparten el plan. TTS cobra el texto facturable; un diálogo suma sus intervenciones. Clonar y diseñar un lote cuestan 1.000 caracteres cada uno. Guardar una candidata no agrega un segundo cargo.

Las consultas y descargas no consumen caracteres. Las herramientas mantienen el coste de su operación, que puede depender de la duración. /capabilities describe disponibilidad y límites; no existe un endpoint de cuenta o saldo.

Los caracteres se reservan antes de ejecutar, se confirman una sola vez al completar y se liberan ante fallos definitivos según la política de la operación. Un diálogo puede tener consumo parcial.

El presupuesto mensual UTC de una clave agrega un límite al saldo compartido y cuenta todas las reservas activas, aunque sean del mes anterior. Crear más claves no amplía la cuota ni la concurrencia. El resultado informa reserved_characters, billed_characters y remaining_characters cuando corresponde.

Notificaciones firmadas

Registra destinos HTTPS desde el panel de desarrolladores para job.completed y job.failed. Guarda el secreto de firma cuando se muestra; también puedes usar polling sin registrar un destino.

Verifica la firma sobre los bytes originales antes de procesar el evento. Valida el timestamp y deduplica por el identificador del evento. Los reintentos pueden entregar el mismo evento varias veces. Responde 2xx después de persistirlo.

El evento contiene id, type, created_at y data: {job_id, status}. La configuración de destinos se administra desde el panel. Usa los ejemplos de verificación y las instrucciones técnicas del proyecto para integrar tu receptor.

Vocloner-Signature usa t=<unix>,v1=<HMAC-SHA256 hexadecimal>. Firma timestamp + un punto + el cuerpo original con el secreto. Rechaza marcas de tiempo con más de cinco minutos de diferencia. Vocloner-Event-Id identifica entregas para deduplicar.

Verificar una notificación en tu servidor

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: Buffer, header: string, secret: string) {
  const match = /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(header);
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(String(timestamp) + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2]!, 'hex'));
}

// Read the ORIGINAL request bytes, before parsing JSON.
export async function handleWebhook(request: Request,
  persistEventOnce: (event: { id: string; type: string;
    data: { job_id: string; status: string } }) => Promise<void>) {
  const rawBody = Buffer.from(await request.arrayBuffer());
  const secret = process.env.VOCLONER_WEBHOOK_SECRET!;
  if (!secret || !verify(rawBody,
      request.headers.get('Vocloner-Signature') ?? '', secret)) {
    return new Response('Invalid signature', { status: 401 });
  }
  const event = JSON.parse(rawBody.toString('utf8'));
  if (event.id !== request.headers.get('Vocloner-Event-Id')) {
    return new Response('Invalid event ID', { status: 400 });
  }
  // Required: atomically insert event.id into a UNIQUE column and
  // persist the job notification in your database. A duplicate ID
  // returns 200 without applying the event again. On DB failure,
  // return 500 so Vocloner can retry. Query /jobs/{job_id} with
  // your API key when you need the authoritative result.
  await persistEventOnce(event);
  return new Response(null, { status: 200 });
}

Errores, retención y soporte

Todos los errores usan error.code, error.message, error.request_id y error.retryable. Conserva X-Request-Id para diagnosticar una solicitud sin almacenar claves o audio en logs.

La paginación devuelve items y next_cursor. Trata el cursor como opaco y pásalo sin modificar. Los identificadores de recursos son UUID; no son identificadores del proveedor.

Los resultados y archivos respetan la retención vigente. Descarga el material que necesites conservar antes de su vencimiento. La primera versión no ofrece streaming temprano, conversación en tiempo real ni un SLA de entrega.

HTTPQué hacer
400 / 422Revisa los campos, formatos y límites indicados por el contrato.
401Reemplaza una clave inválida, vencida o revocada.
403Revisa permisos, consentimiento y funciones habilitadas por el plan.
404Verifica el ID y el propietario del recurso.
409Reutiliza el contenido original o una clave nueva para una operación nueva.
413Reduce el archivo según los límites del propósito.
429Revisa cuotas y concurrencia; respeta Retry-After.
500 / 503Guarda request_id y reintenta solo si corresponde, con la misma Idempotency-Key.

Referencia de endpoints

Los identificadores y resultados de los ejemplos son ilustrativos. Reemplázalos por recursos autorizados de tu cuenta.

26 / 26

GET/voicesListar voces

Voces propias y públicas autorizadas. Usa cursor y limit para paginar.

Permiso requerido
voices:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/voices' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "items": [
    {
      "id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
      "name": "Example voice",
      "visibility": "private",
      "language": "es",
      "category": "narrator",
      "status": "ready",
      "avatar_url": null,
      "review_state": "approved",
      "created_at": "2026-10-29T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/voices/{id}Consultar una voz

Obtén metadatos de una voz que puedes utilizar.

Permiso requerido
voices:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/voices/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
  "name": "Example voice",
  "visibility": "private",
  "language": "es",
  "category": "narrator",
  "status": "ready",
  "avatar_url": null,
  "review_state": "approved",
  "created_at": "2026-10-29T12:00:00.000Z"
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/voicesClonar una voz

Sube y confirma una grabación antes de clonar. Si se exige un reto, aporta también su grabación. Las voces nuevas son privadas.

Permiso requerido
voices:clone
Consumo
1.000 caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
file_idstring · uuidObligatorio
namestring · length 1–120Obligatorio
consent_ownershipbooleanObligatorio
languagestring · length 2–40 · default: "es"Opcional
categorystring · length 2–40 · default: "narrator"Opcional
localestring · es | en · default: "es"Opcional
consent_challenge_idstring · uuidOpcional
consent_file_idstring · uuidOpcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/voices' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"file_id":"ab198ae5-9225-40f3-b176-56ed83861080","name":"Mi voz","consent_ownership":true,"language":"es","category":"narrator","locale":"es"}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "clone",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 1000,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
PATCH/voices/{id}Editar una voz

Modifica el nombre, idioma o categoría de una voz propia.

Permiso requerido
voices:write
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
namestring · length 1–120Opcional
languagestring · length 2–40 · default: "es"Opcional
categorystring · length 2–40 · default: "narrator"Opcional

Ejemplos de solicitud

curl --request PATCH 'https://api.vocloner.org/v1/voices/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Narración"}'

Respuesta

200 · application/json

{
  "id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
  "name": "Example voice",
  "visibility": "private",
  "language": "es",
  "category": "narrator",
  "status": "ready",
  "avatar_url": null,
  "review_state": "approved",
  "created_at": "2026-10-29T12:00:00.000Z"
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
DELETE/voices/{id}Eliminar una voz

Elimina una voz propia. Las generaciones existentes conservan sus reglas de retención.

Permiso requerido
voices:delete
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request DELETE 'https://api.vocloner.org/v1/voices/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "deleted": true
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/voices/{id}/publication-requestsSolicitar publicación

Confirma el permiso de uso público y solicita revisión. Solicitar no publica automáticamente la voz.

Permiso requerido
voices:publish
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
consent_public_usebooleanObligatorio

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/voices/c816ce5b-22f5-4ed2-91a9-90e79b874a24/publication-requests' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"consent_public_use":true}'

Respuesta

201 · application/json

{
  "voice_id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
  "review_state": "pending"
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/voices/{id}/reportsReportar una voz

Comunica suplantación, falta de consentimiento u otro abuso para su revisión.

Permiso requerido
voices:report
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
reasonstring · impersonation | no_consent | offensive | spam | otherObligatorio
detailstring · length 0–1000Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/voices/c816ce5b-22f5-4ed2-91a9-90e79b874a24/reports' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"reason":"no_consent","detail":"Información para la revisión."}'

Respuesta

200 · application/json

{
  "reported": true
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/voice-designsDiseñar candidatas

Describe una voz para obtener candidatas temporales. Guarda una candidata antes de utilizarla en TTS.

Permiso requerido
voices:design
Consumo
1.000 caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
promptstring · length 8–1000Obligatorio

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/voice-designs' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"Una voz cálida, clara y pausada para narración en español."}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "voice_design",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 1000,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/voice-designs/{id}Consultar un diseño

Consulta candidatas y vencimiento del lote propio.

Permiso requerido
voices:design
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/voice-designs/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "voice_design",
  "status": "completed",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": "2026-10-29T12:00:00.000Z",
  "completed_at": "2026-10-29T12:00:00.000Z",
  "cancel_requested": false,
  "result": {
    "design_id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
    "candidates": [
      {
        "id": "6e657fb6-cf58-46d8-9311-7f3828b203c7",
        "index": 0,
        "duration_ms": 3500,
        "audio_url": "https://api.vocloner.org/v1/assets/6e657fb6-cf58-46d8-9311-7f3828b203c7/content"
      }
    ]
  },
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 46,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/voice-designs/{id}/voicesGuardar una candidata

Crea una voz privada reutilizable sin volver a cobrar el diseño. Requiere un slot de voz disponible.

Permiso requerido
voices:design
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
candidate_idstring · uuidObligatorio
namestring · length 1–120Obligatorio
languagestring · length 2–40 · default: "es"Opcional
categorystring · length 2–40 · default: "narrator"Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/voice-designs/c816ce5b-22f5-4ed2-91a9-90e79b874a24/voices' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"candidate_id":"c816ce5b-22f5-4ed2-91a9-90e79b874a24","name":"Narradora","language":"es","category":"narrator"}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "voice_design_select",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/speechGenerar audio

Convierte texto en MP3 o WAV. Acepta etiquetas expresivas compatibles. Prefer: wait=20 espera hasta veinte segundos; puede devolver 202.

Permiso requerido
speech:generate
Consumo
Caracteres facturables del texto

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
voice_idstring · uuidObligatorio
textstring · length 1–12000Obligatorio
formatstring · mp3 | wav · default: "mp3"Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/speech' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"voice_id":"c816ce5b-22f5-4ed2-91a9-90e79b874a24","text":"Hola, esta es mi primera generación con Vocloner.","format":"mp3"}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "speech",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/dialoguesGenerar un diálogo

Entre dos y diez intervenciones. Cada voz debe estar autorizada y el plan debe permitir diálogos.

Permiso requerido
speech:generate
Consumo
Caracteres facturables del texto

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
linesarray · items 2–10Obligatorio
lines[].voice_idstring · uuidObligatorio
lines[].textstring · length 1–12000Obligatorio
gap_msinteger · 0–3000 · default: 400Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/dialogues' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"lines":[{"voice_id":"c816ce5b-22f5-4ed2-91a9-90e79b874a24","text":"Hola."},{"voice_id":"c816ce5b-22f5-4ed2-91a9-90e79b874a24","text":"Bienvenido."}],"gap_ms":400}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "dialogue",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/filesPreparar una subida

Recibe una autorización temporal para subir directamente al Storage privado. Después confirma la subida con /complete.

Permiso requerido
files:write
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
file_namestring · length 1–180Obligatorio
content_typestring · audio/mpeg | audio/mp3 | audio/wav | audio/x-wav | audio/wave | audio/ogg | audio/flac | audio/x-flac | audio/mp4 | audio/m4a | audio/x-m4a | audio/webmObligatorio
size_bytesinteger · …–26214400Obligatorio
purposestring · clone | audio_tool | local_tool | consentObligatorio

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/files' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"file_name":"voz.wav","content_type":"audio/wav","size_bytes":1048576,"purpose":"clone"}'

Respuesta

201 · application/json

{
  "id": "ab198ae5-9225-40f3-b176-56ed83861080",
  "file_name": "voz.wav",
  "content_type": "audio/wav",
  "size_bytes": 1048576,
  "duration_ms": null,
  "sha256": null,
  "purpose": "clone",
  "status": "pending",
  "created_at": "2026-10-29T12:00:00.000Z",
  "expires_at": "2026-10-30T12:00:00.000Z",
  "upload_url": "https://storage.example.com/signed-upload/illustrative-only",
  "upload_token": "ILLUSTRATIVE_UPLOAD_TOKEN",
  "upload_expires_at": "2026-10-29T12:00:00.000Z",
  "upload_method": "PUT",
  "upload_headers": {
    "Content-Type": "audio/wav"
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/files/{id}/completeConfirmar una subida

Comprueba el contenido real, tamaño, duración y hash antes de permitir su uso.

Permiso requerido
files:write
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/files/c816ce5b-22f5-4ed2-91a9-90e79b874a24/complete' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES'

Respuesta

200 · application/json

{
  "id": "ab198ae5-9225-40f3-b176-56ed83861080",
  "file_name": "voz.wav",
  "content_type": "audio/wav",
  "size_bytes": 1048576,
  "duration_ms": 12000,
  "sha256": null,
  "purpose": "clone",
  "status": "ready",
  "created_at": "2026-10-29T12:00:00.000Z",
  "expires_at": "2026-10-30T12:00:00.000Z"
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/files/{id}Consultar un archivo

Consulta estado, duración y vencimiento de un archivo propio.

Permiso requerido
files:write
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/files/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "ab198ae5-9225-40f3-b176-56ed83861080",
  "file_name": "voz.wav",
  "content_type": "audio/wav",
  "size_bytes": 1048576,
  "duration_ms": 12000,
  "sha256": null,
  "purpose": "clone",
  "status": "ready",
  "created_at": "2026-10-29T12:00:00.000Z",
  "expires_at": "2026-10-30T12:00:00.000Z"
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
DELETE/files/{id}Eliminar un archivo

Elimina un archivo propio cuando ningún trabajo activo lo necesita.

Permiso requerido
files:write
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request DELETE 'https://api.vocloner.org/v1/files/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "ab198ae5-9225-40f3-b176-56ed83861080",
  "deleted": true
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/consent-challengesObtener un reto

Obtén una frase temporal, grábala y sube el audio con purpose: consent. Adjunta ambos identificadores al clonar.

Permiso requerido
voices:clone
Consumo
Sin cargo de caracteres

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
localestring · es | en · default: "es"Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/consent-challenges' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"locale":"es"}'

Respuesta

201 · application/json

{
  "id": "ab198ae5-9225-40f3-b176-56ed83861080",
  "phrase": "Read the challenge returned by your live request.",
  "expires_at": "2026-10-29T12:00:00.000Z",
  "consent_version": "example-version",
  "consent_text": "The live response provides the applicable consent text.",
  "recording_required": true
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/audio-tools/{operation}Procesar audio

Consulta /capabilities para operaciones y opciones habilitadas. Aporta exactamente un archivo o una generación propia.

Permiso requerido
audio:process
Consumo
Según operación; consulta capabilities

Cuerpo de la solicitud

CampoTipo y límitesObligatorio
file_idstring · uuidOpcional
generation_idstring · uuidOpcional
optionsobject · default: {}Opcional
options.start_msinteger · 0–9007199254740991Opcional
options.end_msinteger · …–9007199254740991Opcional
options.volumenumber · 0–4Opcional
options.fade_in_msinteger · 0–30000Opcional
options.fade_out_msinteger · 0–30000Opcional
options.target_peak_dbnumber · -24–-0.1Opcional

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/audio-tools/trim' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES' \
  --header 'Content-Type: application/json' \
  --data '{"file_id":"ab198ae5-9225-40f3-b176-56ed83861080","options":{"start_ms":0,"end_ms":5000}}'

Respuesta

202 Accepted · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "audio_tool",
  "status": "queued",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "cancel_requested": false,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/jobsListar trabajos

Historial paginado de trabajos propios, ordenado por creación.

Permiso requerido
jobs:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/jobs' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "items": [
    {
      "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
      "operation": "speech",
      "status": "completed",
      "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
      "created_at": "2026-10-29T12:00:00.000Z",
      "started_at": "2026-10-29T12:00:00.000Z",
      "completed_at": "2026-10-29T12:00:00.000Z",
      "cancel_requested": false,
      "result": {
        "generation_id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
        "asset_id": "6e657fb6-cf58-46d8-9311-7f3828b203c7",
        "audio_url": "https://api.vocloner.org/v1/assets/6e657fb6-cf58-46d8-9311-7f3828b203c7/content",
        "format": "mp3",
        "duration_ms": 3500
      },
      "error": null,
      "usage": {
        "reserved_characters": 46,
        "billed_characters": 46,
        "remaining_characters": 9000
      }
    }
  ],
  "next_cursor": null
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/jobs/{id}Consultar un trabajo

Consulta estado, resultado y caracteres cobrados. Respeta Retry-After antes de volver a consultar.

Permiso requerido
jobs:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/jobs/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "speech",
  "status": "completed",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": "2026-10-29T12:00:00.000Z",
  "completed_at": "2026-10-29T12:00:00.000Z",
  "cancel_requested": false,
  "result": {
    "generation_id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
    "asset_id": "6e657fb6-cf58-46d8-9311-7f3828b203c7",
    "audio_url": "https://api.vocloner.org/v1/assets/6e657fb6-cf58-46d8-9311-7f3828b203c7/content",
    "format": "mp3",
    "duration_ms": 3500
  },
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 46,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
POST/jobs/{id}/cancelCancelar un trabajo

Cancela inmediatamente en cola. Si comenzó, solicita cancelación y consulta el estado y consumo final.

Permiso requerido
jobs:cancel
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request POST 'https://api.vocloner.org/v1/jobs/c816ce5b-22f5-4ed2-91a9-90e79b874a24/cancel' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: REUSE_THIS_KEY_FOR_RETRIES'

Respuesta

200 · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "operation": "speech",
  "status": "canceled",
  "status_url": "https://api.vocloner.org/v1/jobs/f261e35c-420f-4c82-bd88-a0e370c936ab",
  "created_at": "2026-10-29T12:00:00.000Z",
  "started_at": "2026-10-29T12:00:00.000Z",
  "completed_at": "2026-10-29T12:00:00.000Z",
  "cancel_requested": true,
  "result": null,
  "error": null,
  "usage": {
    "reserved_characters": 46,
    "billed_characters": 0,
    "remaining_characters": 9000
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/generationsListar generaciones

Consulta las generaciones propias de la web, MCP y API mediante cursor estable.

Permiso requerido
generations:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/generations' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "items": [
    {
      "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
      "kind": "tts",
      "voice_id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
      "status": "completed",
      "char_count": 46,
      "duration_ms": 3500,
      "format": "mp3",
      "audio_asset_id": "6e657fb6-cf58-46d8-9311-7f3828b203c7",
      "audio_url": "https://api.vocloner.org/v1/assets/6e657fb6-cf58-46d8-9311-7f3828b203c7/content",
      "created_at": "2026-10-29T12:00:00.000Z",
      "completed_at": "2026-10-29T12:00:00.000Z",
      "error_code": null
    }
  ],
  "next_cursor": null
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/generations/{id}Consultar una generación

Consulta metadatos de una generación propia y su referencia de audio.

Permiso requerido
generations:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/generations/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "id": "f261e35c-420f-4c82-bd88-a0e370c936ab",
  "kind": "tts",
  "voice_id": "c816ce5b-22f5-4ed2-91a9-90e79b874a24",
  "status": "completed",
  "char_count": 46,
  "duration_ms": 3500,
  "format": "mp3",
  "audio_asset_id": "6e657fb6-cf58-46d8-9311-7f3828b203c7",
  "audio_url": "https://api.vocloner.org/v1/assets/6e657fb6-cf58-46d8-9311-7f3828b203c7/content",
  "created_at": "2026-10-29T12:00:00.000Z",
  "completed_at": "2026-10-29T12:00:00.000Z",
  "error_code": null
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
DELETE/generations/{id}Eliminar una generación

Elimina una generación propia según las reglas de retención.

Permiso requerido
generations:delete
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request DELETE 'https://api.vocloner.org/v1/generations/c816ce5b-22f5-4ed2-91a9-90e79b874a24' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "deleted": true
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/assets/{id}/contentDescargar audio

Devuelve bytes de audio autorizado. Envía Bearer en cada descarga; no coloques la clave en la URL.

Permiso requerido
audio:read
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/assets/c816ce5b-22f5-4ed2-91a9-90e79b874a24/content' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 OK · audio/mpeg / audio/wav

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación
GET/capabilitiesConsultar capacidades

Consulta formatos, operaciones y límites admitidos en este entorno antes de integrar.

Permiso requerido
API key válida
Consumo
Sin cargo de caracteres

Ejemplos de solicitud

curl --request GET 'https://api.vocloner.org/v1/capabilities' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · application/json

{
  "api_version": "v1",
  "formats": {
    "speech": [
      "mp3",
      "wav"
    ],
    "dialogue": [
      "mp3"
    ]
  },
  "operations": [
    "speech",
    "dialogue",
    "clone",
    "voice_design",
    "voice_design_select",
    "audio_tool"
  ],
  "audio_tools": {
    "trim": true,
    "volume": true,
    "fade": true,
    "reverse": true,
    "normalize": true,
    "denoise": false,
    "separate": false
  },
  "files": {
    "clone": {
      "max_bytes": 20971520,
      "min_seconds": 5,
      "max_seconds": 270
    },
    "consent": {
      "max_bytes": 5242880
    },
    "audio_tool": {
      "max_bytes": 20971520,
      "max_seconds": 1200
    },
    "local_tool": {
      "max_bytes": 26214400,
      "max_seconds": 900
    }
  },
  "consent": {
    "version": "example-version",
    "recording_required": true
  },
  "jobs": {
    "default_mode": "async",
    "max_wait_seconds": 20
  },
  "idempotency": {
    "retention_days": 30
  }
}

Las operaciones largas devuelven un trabajo. Consulta status_url hasta un estado final. Todos los errores incluyen request_id.

Errores y recuperación

Prueba una generación

La clave queda en memoria y se borra al salir. El audio se descarga con autorización. Nunca uses una clave de producción en código del navegador.

La API está deshabilitada en este entorno. La referencia es pública; las solicitudes reales todavía no están disponibles.

Consumo estimado: 49 caracteres. El servidor confirma el consumo final y aplica los límites de tu plan.

Changelog

v1 · Voces, audio y trabajos con cuotas compartidas. La disponibilidad real depende del entorno y se consulta en capabilities.