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.

Obtener una clave de API Inicio rápido Idiomas compatibles

Última actualización: · Markdown

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:

{
  "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

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 productoAjustePor qué
Audio limpio, mucho volumen, poco costemodel: "base"0,40 créditos (0,48 US$) por hora
Por defecto para archivos de usuariosmodel: "oracle"Calidad de producción, con traducción
Transcripción en otro idiomaModelo Oracle + translate_toUna tarea, texto traducido
Quién dijo quéinclude_diarization: trueIncluido en el precio
Subtítulosoutput_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