Skip to main content

​
Quick Start

​
Request

import { Supadata } from "@supadata/js";

// Initialize the client
const supadata = new Supadata({
  apiKey: "YOUR_API_KEY",
});

// Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file
const transcriptResult = await supadata.transcript({
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  lang: "en", // optional
  text: true, // optional: return plain text instead of timestamped chunks
  mode: "auto", // optional: 'native', 'auto', or 'generate'
});

​
Response

{
  "content": "Never gonna give you up, never gonna let you down...",
  "lang": "en",
  "availableLangs": ["en", "es", "zh-TW"]
}

​
Specification

​
Endpoint

GET https://api.supadata.ai/v1/transcript Each request requires an x-api-key header with your API key available after signing up. Get your API key here.

​
Query Parameters

ParameterTypeRequiredDescription
urlstringYesURL of the video to get transcript from. Must be either YouTube, TikTok, Instagram, X (Twitter) or a public file URL. It is recommended to encode the URL before sending it as a query parameter.
langstringNoPreferred language code of the transcript (ISO 639-1). See Languages.
textbooleanNoWhen true, returns plain text transcript. Default: false
chunkSizenumberNoMaximum characters per transcript chunk (only when text=false)
modestringNoTranscript mode: native (only fetch existing transcript), generate (always generate transcript using AI), or auto (try native, fallback to generate if unavailable). If url is a file URL, mode is always generate. Default: auto.
To fetch only existing transcripts and avoid costs tied to AI generation, use mode=native.

​
Response Format

The API can return either a transcript result directly (HTTP 200) or a job ID for asynchronous processing (HTTP 202).
For large videos that require processing time, the API returns HTTP 202 with a job ID. Use the /transcript/{jobId} endpoint to poll for results.
Immediate transcript response (HTTP 200): When text=true: 
{
  "content": string,
  "lang": string             // ISO 639-1 language code
  "availableLangs": string[] // List of available languages
}
When text=false: 
{
  "content": [
    {
      "text": string,        // Transcript segment
      "offset": number,      // Start time in milliseconds
      "duration": number,    // Duration in milliseconds
      "lang": string         // ISO 639-1 language code of chunk
    }
  ],
  "lang": string             // ISO 639-1 language code of transcript
  "availableLangs": string[] // List of available languages
}
Asynchronous job response (HTTP 202): 
{
  "jobId": string // Job ID for checking results
}

​
Getting Job Results

When the API returns a job ID, you can poll for results using the job ID endpoint: 
import { Supadata } from "@supadata/js";

// Check if we got a transcript directly or a job ID for async processing
if ("jobId" in transcriptResult) {
  // For large files, we get a job ID and need to poll for results
  const jobResult = await supadata.transcript.getJobStatus(
    transcriptResult.jobId
  );
  if (jobResult.status === "completed") {
    console.log(jobResult.content);
  } else if (jobResult.status === "failed") {
    console.error(jobResult.error);
  } else {
    console.log("Job status:", jobResult.status);
  }
} else {
  // For smaller files or native transcripts, we get the result directly
  console.log("Transcript:", transcriptResult);
}

​
Response

{
  "status": "completed",
  "content": "Never gonna give you up, never gonna let you down...",
  "lang": "en",
  "availableLangs": ["en", "es", "zh-TW"]
}

​
Job Status Values

StatusDescription
queuedThe job is in the queue waiting to be processed
activeThe job is currently being processed
completedThe job has finished and results are available
failedThe job failed due to an error

​
Error Codes

The API returns HTTP status codes and error codes. See this page for more details.

​
Supported URL Formats

url parameter supports the following:
  • YouTube video URL, e.g. https://www.youtube.com/watch?v=1234567890
  • TikTok video URL, e.g. https://www.tiktok.com/@username/video/1234567890
  • X (Twitter) video URL, e.g. https://x.com/username/status/1234567890
  • Instagram video URL, e.g. https://instagram.com/reel/1234567890/
  • Publicly accessible file URL, e.g. https://bucket.s3.eu-north-1.amazonaws.com/file.mp4

​
File Transcripts

When url is a file URL, the endpoint supports the following file formats:
  • MP4
  • WEBM
  • MP3
  • FLAC
  • MPEG
  • M4A
  • OGG
  • WAV
The maximum file size is 1 GB. There is no limit on the video duration.

​
Languages

The endpoint supports multiple languages. The lang parameter is used to specify the preferred language of the transcript. If the video does not have a transcript in the preferred language, the endpoint will return a transcript in the first available language and a list of other available languages. It is then possible to make another request to get the transcript in your chosen fallback language. When mode = generate, the lang parameter is ignored and the transcript is generated in the language of the video.

​
Pricing

  • 1 native transcript = 1 credit
  • 1 generated transcript minute = 2 credits