Documentación de la API de KolWrite

Autenticación

Todas las solicitudes a la API deben autenticarse con tu clave de API única. Inclúyela en las cabeceras de la solicitud:

x-api-key: YOUR_API_KEY

Puedes generar y gestionar tus claves de API desde « Consola de KolWrite » después de crear una cuenta.

Inicio rápido

Empieza rápidamente con estos ejemplos básicos.

1. Iniciar la transcripción

Envía una solicitud POST al endpoint `/transcribe` con la URL del archivo de audio que quieras transcribir.

Solicitud:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Respuesta:

La API devuelve un `jobId` que utilizarás para recuperar los resultados de la transcripción.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Obtener el resultado de la transcripción

De Send a GET request a the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Solicitud:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Respuesta (ejemplo):

Cuando el estado del trabajo sea COMPLETED, la respuesta incluirá los detalles de la transcripción.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Modelos y créditos de uso

El uso del modelo se mide en créditos de uso por segundo, sin cargo mínimo. El pago, los recibos y los documentos fiscales muestran la moneda de pago real utilizada en la compra.

1 crédito es la unidad de facturación de la API que antes se mostraba como $1.00 en la consola de la API.

Las cuentas de facturación israelíes que cumplan los requisitos compran créditos de uso en ILS a un precio neto de ILS 3.60 por crédito antes del IVA. Antes del pago, se muestran los créditos de uso, el importe neto, el IVA y el total final en ILS. Las demás cuentas compran créditos de uso en USD a USD 1.20 por crédito, salvo que se apliquen condiciones de pedido independientes.

Complementos: La diarización estándar de hablantes y la separación por canales en modo standard están incluidas. La diarización Pro de hablantes añade 0.20 créditos de uso por hora de audio. overlap la separación de canales se factura a la tarifa del modelo seleccionado por el mayor valor entre la duración de la grabación y el tiempo total de habla detectado en sus canales físicos; ningún modo de canal añade un recargo por diarización. Oracle Mini habilita automáticamente la alineación de marcas de tiempo cuando se selecciona diarización de hablantes o separación de canales.

Endpoints de la API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Envía un archivo de audio para transcribirlo de forma asíncrona, con diarización de hablantes opcional.

Parámetros del cuerpo de la solicitud

Solicitud de ejemplo (con diarización):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Respuesta:

Devuelve un objeto que contiene el `jobId` de la tarea de transcripción enviada.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Recupera el estado y el resultado de un trabajo de transcripción concreto.

Parámetros de ruta

Cuerpo de la respuesta

Respuesta de ejemplo (salida JSON con diarización de hablantes):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Diarización de hablantes

La diarización de hablantes es el proceso de identificar y separar a los distintos hablantes de una grabación de audio. Cuando se activa, KolWrite analiza el audio para detectar los cambios de hablante y etiqueta cada segmento según corresponda.

La diarización de hablantes y la separación de canales están disponibles con todos los modelos indicados. Oracle Mini habilita automáticamente la alineación de marcas de tiempo siempre que se selecciona un modo de hablantes.

Cómo activar la diarización

Para activar la diarización de hablantes, establece el parámetro include_diarization en true en tu solicitud de transcripción:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Optimización del número de hablantes

Para obtener los mejores resultados, indica el número previsto de hablantes mediante el parámetro num_speakers . Si no conoces el número exacto, puedes:

• Omitir el parámetro (el sistema lo detectará automáticamente)
• Indica un intervalo estimado según tu mejor cálculo

Diarización Pro

Para obtener mayor precisión al identificar a los hablantes, sobre todo en condiciones acústicas complejas, puedes activar la diarización Pro. Esta función tiene un coste adicional de 0.20 créditos de uso por hora de audio.

Para utilizarla, establece el parámetro pro_diarization en true. Este parámetro puede usarse junto con include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Separación de hablantes por canales

La separación por canales transcribe cada pista física de audio por separado y etiqueta los segmentos y las palabras devueltos con sus campos físicos channel y speaker. Requiere una fuente de entre dos y ocho canales indicada mediante audio_url y no se puede combinar con diarización normal o Pro. Oracle Mini habilita automáticamente la alineación de marcas de tiempo para cualquiera de los modos de canal.

Usar standard cuando los hablantes intervienen por turnos; se factura una sola tarifa de audio del modelo seleccionado. Usa overlap cuando los hablantes pueden solaparse; se factura la tarifa del modelo seleccionado por el mayor valor entre la duración de la grabación y el tiempo total de habla detectado en sus canales físicos.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhooks de finalización

Establece webhook_url para recibir transcription.completed y transcription.failed eventos. Los envíos fallidos se vuelven a intentar, pero los clientes deben seguir admitiendo GET /transcribe/{jobId} como fuente de referencia.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Cada envío incluye X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id, y X-KolWrite-Timestamp. La entrega se realiza al menos una vez; los reintentos reutilizan el mismo ID de entrega, así que elimina los eventos duplicados mediante X-KolWrite-Delivery-Id. Cuando haya un secreto configurado, calcula HMAC-SHA256 sobre timestamp + "." + raw_request_body y compáralo con X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

Para output_format: "json", el webhook result es un objeto JSON. Los resultados TXT y SRT se entregan como cadenas.

En los resultados de gran tamaño, se puede establecer result_omitted en true; obtén el resultado completo de GET /transcribe/{jobId}. Los eventos fallidos incluyen un campo error campo.

Formato de salida con diarización

Cuando la diarización está activada, cada segmento de la salida JSON incluye el campo speaker que identifica al hablante (p. ej., «Hablante 1», «Hablante 2», etc.).

Formatos de salida

Formato JSON

Salida detallada con segmentos, marcas de tiempo y datos opcionales por palabra.

Formato TXT

Transcripción en texto sin formato con etiquetas de hablante (cuando la diarización está activada).

Formato SRT

Formato de subtítulos SubRip con marcas de tiempo, compatible con reproductores de vídeo y editores de subtítulos.

Estado del servicio

Consulta la página de estado de la API de KolWrite para consultar la disponibilidad en tiempo real, el historial de actividad y los incidentes del nivel de servicio.

GET /health no requiere una clave de API y devuelve el estado actual de la API, la recepción de trabajos y el procesamiento de transcripciones. Una respuesta 200 significa que el servicio está operativo o degradado; una respuesta 503 significa que el estado actual es desconocido o no está disponible. Ambas respuestas incluyen detalles de estado en JSON.

GET /health/history?period=24h devuelve un historial de disponibilidad compacto. Los periodos admitidos son 24h, 7d, y 30d.

Códigos de estado