# SDK para Node.js

> Transcribe enlaces y archivos con @transcript1/sdk desde tu servidor. Descarga texto o subtítulos, consulta el progreso y maneja los errores.

Canonical: https://transcript1.com/es/docs/sdk
Language: es
Last updated: 2026-10-16

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

```bash
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”](https://transcript1.com/dashboard/account/tokens). Puedes guardarla en la variable de entorno `TRANSCRIPT1_API_KEY` de tu servidor o pasarla al constructor mediante `apiKey`:

```javascript
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.

```javascript
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:

```javascript
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](https://transcript1.com/es/docs/sources-and-options) 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](https://transcript1.com/es/docs/sources-and-options).

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.

```javascript
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.

```javascript
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

```javascript
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`:

| Opción | Para qué sirve |
|---|---|
| `speakers` | Activa la identificación de hablantes. |
| `language` | Indica un código ISO 639-1 o deja `auto`, el valor por defecto. |
| `source` | Para enlaces, elige `auto` o `stt`. En YouTube, X, TikTok, Bluesky, Dailymotion y LinkedIn también puedes elegir `captions` si hay una pista válida. |
| `fresh` | Fuerza una nueva transcripción del enlace en lugar de reutilizar una de las últimas 24 horas. |
| `filename` | Indica el nombre para Buffers, Blobs sin nombre y streams; es obligatorio en esos casos. También permite cambiar el nombre de un archivo. |
| `size` | Indica el tamaño en bytes. Es obligatorio para streams e iterables asíncronos. |
| `idempotencyKey` | Usa una clave propia; si no la indicas, cada llamada genera un UUID nuevo. |
| `onProgress` | Recibe avisos de cómo avanza la operación. |
| `signal` | Pasa un AbortSignal para poder cancelar la llamada. |

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:

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

| Evento | Datos que recibes |
|---|---|
| `upload` | Bytes enviados en `sent` y tamaño completo en `total`. |
| `status` | Estado actual de la transcripción en `status`. |
| `waiting_slot` | Segundos que faltan para volver a buscar un lugar disponible, en `retryAfter`. |
| `reconnecting` | No añade campos. Se emite una vez por cada interrupción de la conexión durante la espera. |

## 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`:

```javascript
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:

```javascript
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);
  }
}
```

| Campo | Qué indica |
|---|---|
| `message` | Explicación del problema. |
| `code` | Código de error de la API, del fallo de transcripción o del SDK; también puede ser `canceled`. |
| `status` | Código HTTP. No aparece en errores locales ni en fallos de transcripción. |
| `details` | Datos adicionales de la API, como `minutes_needed` o `action_url`. Si no hay datos, es un objeto vacío. |
| `retryable` | Indica si tiene sentido reintentar. Por defecto es `false`. |
| `transcriptionId` | ID de la transcripción, si ya existe. |
| `transcription` | Objeto más reciente de la transcripción, si está disponible. |

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](https://transcript1.com/es/docs/errors); los campos de cada respuesta, en la [referencia de la API](https://transcript1.com/es/docs/api-reference).

## 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.