# Transcripción para apps y productos SaaS

> Añade notas de voz, transcripciones de reuniones, subtítulos o audio buscable a tu producto con una API REST asíncrona: sube, inicia una tarea, recibe el webhook y guarda los segmentos.

Última actualización: 2026-10-08 · HTML: https://console.kolwrite.com/es/use-cases/developers

## El flujo en producción

1. Tu backend llama a `POST /upload` para el archivo del usuario y devuelve el formulario firmado al cliente, o lo sube él mismo (hasta 100 MiB).
2. Inicia la tarea con el `fileUrl` devuelto como `audio_url` y tu `webhook_url`.
3. Verifica la firma del webhook, descarta duplicados por `X-KolWrite-Delivery-Id` y consulta `GET /transcribe/{jobId}` si `result_omitted` es true.
4. Guarda los `segments` (texto, tiempos, hablantes) y muéstralos; exporta `srt` o `txt` cuando haga falta.

Solicitud de la tarea:

```json
{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}
```

## Verificar webhooks

```javascript
import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

Las entregas llegan al menos una vez y se reintentan si fallan. `GET /transcribe/{jobId}` sigue siendo la fuente de verdad.

## Elegir el modelo por tarea

| Necesidad del producto | Ajuste | Por qué |
| --- | --- | --- |
| Audio limpio, mucho volumen, poco coste | `model: "base"` | 0,40 créditos (0,48 US$) por hora |
| Por defecto para archivos de usuarios | `model: "oracle"` | Calidad de producción, con traducción |
| Transcripción en otro idioma | Modelo Oracle + `translate_to` | Una tarea, texto traducido |
| Quién dijo qué | `include_diarization: true` | Incluido en el precio |
| Subtítulos | `output_format: "srt"` | Listos para reproductores de vídeo |

## Límites a tener en cuenta

- Subida Base64 en línea: 4 MiB de medio decodificado. Subida firmada: 100 MiB.
- El formulario firmado caduca a los 60 minutos; la URL de lectura a las 24 horas.
- Las tareas son asíncronas: muestra el progreso con `PENDING` e `IN_PROGRESS`.
- `channel_speaker_separation` no se puede combinar con la diarización.

## Preguntas y respuestas

### ¿Hay un SDK?

La API es HTTPS y JSON simples; sirve cualquier cliente HTTP. El archivo OpenAPI 3.1 en /openapi.json funciona con generadores de código.

### ¿Cómo evito procesar dos veces un webhook?

Descarta duplicados por `X-KolWrite-Delivery-Id`; los reintentos reutilizan ese identificador.

### ¿Cómo se factura el uso?

Por segundo de audio a la tarifa en créditos del modelo, sin mínimo. 1 crédito equivale a 1,20 US$.

## Páginas relacionadas

- [Agentes de IA y vibe coding](https://console.kolwrite.com/es/use-cases/ai-agents)
- [Centros de llamadas y ventas](https://console.kolwrite.com/es/use-cases/call-centers)
- [Empresas](https://console.kolwrite.com/es/use-cases/enterprise)
- [Idiomas compatibles](https://console.kolwrite.com/es/languages/)

---
Obtener una clave de API: https://console.kolwrite.com/auth?lang=es · Documentación de la API: https://console.kolwrite.com/es/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt