SDK para Node.js

Con @transcript1/sdk puedes enviar enlaces o archivos y obtener la transcripción desde tu servidor en TypeScript o JavaScript. El SDK se encarga de las subidas y de esperar hasta que el texto esté listo.

Para los enlaces de redes sociales necesitas el SDK 1.1.0 o posterior. La versión 1.0.1 solo acepta YouTube y rechaza los demás enlaces antes de enviarlos a la API. Actualiza con npm i @transcript1/sdk@latest.

Ese mínimo corresponde a las seis plataformas originales. Para Twitch, Dailymotion, Pinterest, LinkedIn y Snapchat, usa una versión que ya incluya su compatibilidad. Un SDK antiguo puede rechazar esos enlaces sin llegar a llamar a la API.

Instala el paquete

npm i @transcript1/sdk

Para ejecutar los ejemplos con módulos ES, guárdalos en archivos .mjs. Si usas .js, configura "type": "module" en package.json. En Node 20.19+ también puedes usar require(), por ejemplo require('@transcript1/sdk').

Configura tu clave de API

Obtén una clave en “API keys”. Puedes guardarla en la variable de entorno TRANSCRIPT1_API_KEY de tu servidor o pasarla al constructor mediante apiKey:

import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });

Si no encuentra una clave, el constructor lanza Transcript1Error con missing_api_key.

Envía un enlace o un archivo

Llama a transcribe(input, options) para crear la transcripción y esperar el texto. Cuando termina, recibes un CompletedTranscription con status: 'completed' y el campo transcript. Si la transcripción falla o se cancela, la promesa se rechaza.

const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);
 
const file = await t1.transcribe('./interview.m4a', { speakers: true });

Si envías un Buffer o Uint8Array, incluye el nombre del archivo. El SDK lo necesita para reconocer el tipo de audio o video:

import { readFile } from 'node:fs/promises';
 
const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });

El SDK interpreta como enlace cualquier cadena que empiece con http:// o https://; las demás se leen como rutas de archivo. Acepta enlaces de YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn y Snapchat. Para las plataformas adicionales se requiere HTTPS. En Fuentes y opciones puedes comprobar qué grabaciones públicas y subtítulos admite cada plataforma.

También puedes subir archivos de hasta 2,000,000,000 bytes con extensión mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm o mkv.

Usa publicaciones públicas. Si una tiene varios videos, solo se transcribe el primero. No necesitas indicar la plataforma: la API la reconoce por el enlace. Revisa los enlaces cortos admitidos y los límites en Fuentes y opciones.

Además de rutas y buffers, puedes enviar un Blob, un ReadableStream<Uint8Array> o un iterable asíncrono de partes Uint8Array. Para un Blob, agrega filename, salvo que sea un File que ya tenga nombre. Para streams e iterables asíncronos, indica tanto filename como size en bytes.

Descarga texto o subtítulos

Usa download(id, options) para esperar a que termine la transcripción y descargarla como cadena. Si eliges JSON, recibes el texto JSON de la API, no un objeto parseado.

const text = await t1.download(done.id); // text is the default
const withTimes = await t1.download(done.id, { timestamps: true });
const srt = await t1.download(done.id, { format: 'srt' });
const vtt = await t1.download(done.id, { format: 'vtt' });
const json = await t1.download(done.id, { format: 'json' });

Solo puedes combinar timestamps: true con text. Con otro formato, la promesa se rechaza con invalid_input. La promesa de download también se rechaza si la transcripción falla o se cancela.

Crea la transcripción y consúltala después

Si no quieres esperar el texto, usa transcriptions.create. Cuando envías un archivo, la llamada sí espera a que termine la subida antes de devolver el control.

const job = await t1.transcriptions.create('./long-interview.mp4');
const now = await t1.transcriptions.get(job.id);
const finished = await t1.transcriptions.get(job.id, { wait: true });

Para consultar el estado actual, llama a get sin wait. Si agregas wait: true, la promesa se resuelve al llegar a completed, failed o canceled. Comprueba finished.status antes de acceder al texto: a diferencia de transcribe, la promesa de get no se rechaza cuando la transcripción falla o se cancela.

Lista y elimina transcripciones; consulta tu cuenta

for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) {
  console.log(item.id, item.created_at);
}
 
await t1.transcriptions.delete(job.id);
const account = await t1.account();
console.log(account.minutes.remaining);

Con list, las páginas se cargan conforme avanzas en la iteración. Puedes filtrar por status o por platform: youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat o upload. Elige de 1 a 100 elementos por página con limit; la API usa 20 por defecto. Los campos conservan el snake_case de la API. Guarda media_id tal como llega, sin interpretar su contenido.

Si la transcripción sigue en curso, delete la cancela. Si ya terminó, elimina el registro y el texto. Con account puedes leer el plan, los minutos y los límites de tu cuenta.

Opciones

Al crear el cliente puedes configurar apiKey, baseUrl, fetch y maxRetries. Si no indicas baseUrl, se usa TRANSCRIPT1_API_URL cuando está definida; en caso contrario, https://api.transcript1.com. Puedes pasar tu propia implementación de fetch. Para maxRetries, el valor por defecto es 2 y se admiten enteros de 0 a 10.

Estas opciones funcionan tanto en transcribe como en transcriptions.create:

Para transcriptions.get, las opciones son wait, includeWords, onProgress y signal. Agrega includeWords: true si necesitas marcas de tiempo por palabra. Durante la espera, onProgress avisa de los cambios.

En download puedes usar format, timestamps y signal; en list, también puedes pasar signal. Para cancelar una llamada a transcriptions.delete(id, options) o account(options), pasa { signal } en sus opciones.

Sigue el progreso

Agrega un callback onProgress a transcribe, transcriptions.create o a transcriptions.get si lo usas con espera:

await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});

Cancela una llamada o limita la espera

Para poder cancelar la llamada, pasa un AbortSignal creado con AbortController. Si prefieres fijar cuánto puede durar, usa AbortSignal.timeout:

await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});

Si cancelas antes del primer request, la promesa se rechaza con aborted y no hay ID de transcripción. Si cancelas durante la subida, el SDK intenta eliminar la transcripción si sigue en awaiting_upload. Después, la promesa se rechaza con aborted e incluye el ID.

Cancelar la espera no detiene la transcripción en el servidor. Conserva el transcriptionId del error para volver a consultarla con transcriptions.get(id, { wait: true }). Si también quieres cancelar la transcripción, llama a transcriptions.delete(id).

Durante la espera, el SDK sigue reintentando sin límite ante errores de red o respuestas HTTP 429, 500, 502, 503 y 504. Espera 2, 4, 8, 16 y después 30 segundos entre reconexiones. Los demás requests respetan maxRetries. Si al crear una transcripción no hay lugar disponible por el límite de transcripciones activas, también espera y reintenta. Usa signal para poner un límite al tiempo total.

Errores

Captura Transcript1Error para distinguir errores de la API, fallos de transcripción y errores del propio SDK:

import { Transcript1Error } from '@transcript1/sdk';
 
try {
  await t1.transcribe('./call.mp3');
} catch (error) {
  if (error instanceof Transcript1Error) {
    console.error(error.code, error.message, error.transcriptionId);
  }
}

El SDK usa los códigos locales missing_api_key, invalid_input, aborted, network_error y upload_token_refused. Si la respuesta de error no es JSON, el código toma la forma http_<status>.

Si la transcripción falla pero no trae un objeto de error, el SDK usa transcription_failed. Si figura como completada pero sigue sin tener texto después de consultarla, la promesa de transcribe se rechaza con internal_error. Los códigos de la API están en Errores; los campos de cada respuesta, en la referencia de la API.

Dónde puedes usarlo

Necesitas Node 20.19+ para usar el SDK. Bun y Deno deberían funcionar gracias a su compatibilidad con node:, aunque las pruebas automatizadas solo se ejecutan en Node. Úsalo en el servidor. Nunca incluyas una clave de API en código que llegue al navegador.