# 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.kolwrite.com`

## 1. Crea un token

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:

```bash
export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.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:

```bash
# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api.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.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:

```bash
curl -X POST https://api.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

```bash
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.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

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

Formatos: `text`, `json`, `srt`, `vtt`. Los artefactos de transcripción
persistentes (con historial de versiones) están disponibles mediante
`GET /api/v1/jobs/JOB_ID/artifacts` y `GET /api/v1/artifacts/{artifact_id}`
con el ámbito `transcripts:read`.

Las descargas de SRT y VTT requieren el plan Plus o superior; los demás planes reciben HTTP 403 con el código `subtitle_export_requires_plus`.

## 6. Opcional: compártela

Con `shares:write`:

```bash
curl -X POST https://api.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

- [Autenticación y ámbitos](/locales/es/authentication.md)
- [Errores y límites de solicitudes](/locales/es/errors.md)
- [Referencia completa de la API](/) · [Especificación OpenAPI](/openapi.json)