KolWrite KolWrite Desarrolladores

Inicio rápido de la API de KolWrite

Automatiza todo lo que haces en la aplicación KolWrite: sube un archivo, transcríbelo con todas las opciones, exporta la transcripción y compártela mediante un token de acceso personal (PAT).

URL base: https://api-prod.kolwrite.com

1. Crea un token

El acceso a la API es autoservicio: cuando tu cuenta haya comprado créditos, actívalo en Ajustes → Cuenta → Acceso a la API. Las llamadas gastan tus créditos.

En la aplicación KolWrite: Ajustes → Cuenta → Acceso a la API → Crear token. Elige los ámbitos que necesites (esta guía usa files:write, jobs:write, jobs:read, transcripts:read). El secreto (kol_...) solo se muestra una vez: guárdalo de forma segura.

Envíalo en cada solicitud:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/billing/balance

2. Sube un archivo

Crea una sesión de subida, envía los bytes con PUT a la URL prefirmada y, a continuación, finaliza la subida:

# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api-prod.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api-prod.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id

Los archivos grandes se suben por partes: la sesión devuelve entonces data.upload_url con valor null y una URL por parte en data.multipart_part_urls. Envía cada parte con PUT, guarda el encabezado ETag de cada respuesta y mándalos a la llamada de finalización como uploaded_parts: una lista de objetos {part_number, etag}.

3. Transcríbelo

Crea un trabajo. profile selecciona la categoría del modelo (oracle, oracle-mini, oracle-pro, oracle-max; puedes consultarlas con GET /api/v1/models) y options contiene todo lo que ofrece el cuadro de diálogo Analizar de la aplicación. Usa una Idempotency-Key para que los reintentos nunca envíen el trabajo dos veces:

curl -X POST https://api-prod.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"

La incrustación de subtítulos funciona del mismo modo con "type": "caption_burn" y un bloque de estilo options.caption_burn; consulta la referencia.

4. Consulta el estado hasta que termine

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting

5. Exporta la transcripción

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

Formatos: text, json, srt, vtt, docx, pdf. La exportación es la transcripción tal como está ahora: las correcciones que se hacen en el editor de KolWrite se incluyen en cuanto se guardan, sin ningún paso extra.

Para leer la transcripción actual de un archivo por su ID de archivo del espacio de trabajo (el mismo texto que se ve en la app), usa GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json con el ámbito transcripts:read. Sus encabezados X-Transcript-Version-Id y X-Transcript-Revision cambian cada vez que cambia la transcripción, así que un proceso que consulta periódicamente sabe cuándo hay algo nuevo. Las versiones guardadas están en GET /api/v1/jobs/JOB_ID/artifacts y GET /api/v1/artifacts/{artifact_id}; una versión guardada es una instantánea fija y no incluye ediciones posteriores.

Para recoger solo transcripciones que una persona aprobó, pide a los revisores que pulsen "Marcar como revisado" en el editor. Desde entonces la llamada de transcripción envía X-Transcript-Review-Status: reviewed hasta la siguiente edición, y require_reviewed=true hace que responda 409 transcript_not_reviewed en cualquier otro caso. GET /api/v1/transcript-reviews?since=... lista los archivos revisados desde tu última consulta. O evita las consultas: añade un webhook con POST /api/v1/webhook-endpoints (ámbito webhooks:manage) para transcript.reviewed, job.completed, job.failed, upload.completed o upload.failed, y comprueba en cada solicitud el encabezado KolWrite-Signature (HMAC-SHA256 de <t>.<raw body> con el secreto del endpoint).

Las descargas de SRT y VTT son gratuitas en todos los planes.

6. Opcional: compártela

Con shares:write:

curl -X POST https://api-prod.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url

Siguiente

Versión Markdown de esta página