Transcribe API JavaScript SDK

Official JavaScript SDK for Transcribe API.

Installation

npm install @transcribe-api/sdk

Usage

import { TranscribeAPI } from "@transcribe-api/sdk";

const client = new TranscribeAPI({
  apiKey: "YOUR_API_KEY",
  showLogs: true,
  polling: {
    interval: 10,
    timeout: 15 * 60,
  },
});

const transcript = await client.transcribe({
  file: "audio.mp3",
});

const asyncJob = await client.transcribe({
  file: "long-audio.mp3",
  multipartConcurrency: 8,
});

const batchJob = await client.batch.transcribe({
  files: [
    { reference_id: "episode_1", file: "a.mp3" },
    { reference_id: "episode_2", file: "b.wav" },
  ],
});

const remoteJob = await client.transcribe({
  file: { url: "https://signed-get-url-from-s3-or-r2" },
});

const remoteBatchJob = await client.batch.transcribe({
  files: [
    { reference_id: "episode_1", url: "https://signed-get-url-1" },
    { reference_id: "episode_2", url: "https://signed-get-url-2" },
  ],
});

const mixedBatchJob = await client.batch.transcribe({
  files: [
    { reference_id: "episode_1", file: "local.mp3" },
    { reference_id: "episode_2", url: "https://signed-get-url-2" },
  ],
});

For Cloudflare Workers and other web-style runtimes, use the Worker entrypoint:

import { TranscribeAPI } from "@transcribe-api/sdk/worker";

Async uploads use signed R2 URLs returned by the API. Multipart upload is used automatically when the backend returns a multipart flow. Async job creation now goes through POST /v1/transcribe for single-file and batch jobs. For batch calls, each item must be { reference_id, file } or { reference_id, url }, and local plus remote entries can be mixed in the same batch. The SDK adds size_bytes automatically for large local files when the backend needs multipart upload. Set polling.interval and optional polling.timeout in seconds on the client to make async jobs wait for completion automatically. The SDK enforces a minimum polling interval of 10 seconds and stops on completed, failed, or insufficient_funds. If polling is not configured, use GET /v1/transcribe/{job_id} manually. The response always includes the core job fields and adds result_url when job_status is completed. The SDK defaults multipartConcurrency to 8 for reliability. You can increase it up to 32 when your network path is stable. For Node path uploads, multipart progress is persisted to a sidecar resume file and the SDK will resume the existing big-file job on the next run instead of starting over. Multipart uploads also adaptively reduce concurrency on retryable transport errors instead of failing the whole upload immediately. Set showLogs: true on the client or per async call to let the SDK print upload URL receipt, upload progress, and the final /upload-completed response automatically. Pass a custom logger object if you want those messages redirected somewhere other than console.

Use @transcribe-api/sdk/worker when you need a runtime-safe build for Cloudflare Workers. The Worker entrypoint supports remote URLs, Blob, File, and byte inputs, but does not support local file path strings or Node.js filesystem resume state.