Quick Start
Request
Response
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
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | URL of the video to get transcript from. Must be either YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. It is recommended to encode the URL before sending it as a query parameter. |
| lang | string | No | Preferred language code of the transcript (ISO 639-1). See Languages. |
| text | boolean | No | When true, returns plain text transcript. Default: false |
| chunkSize | number | No | Maximum characters per transcript chunk (only when text=false) |
| mode | string | No | Transcript 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. See Pricing for details.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.text=true:
text=false:
Getting Job Results
When the API returns a job ID, you can poll for results using the job ID endpoint:Response
Job Status Values
| Status | Description |
|---|---|
| queued | The job is in the queue waiting to be processed |
| active | The job is currently being processed |
| completed | The job has finished and results are available |
| failed | The job failed due to an error |
Poll the job status endpoint until the status is either “completed” or
“failed”. The
result field will contain the transcript data when status is
“completed”, or the error field will contain error details when status is
“failed”.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/ - Facebook video URL, e.g.
https://www.facebook.com/reel/682865820350105/ - Publicly accessible file URL, e.g.
https://bucket.s3.eu-north-1.amazonaws.com/file.mp4
File Transcripts
Whenurl is a file URL, the endpoint supports the following file formats:
- MP4
- WEBM
- MP3
- FLAC
- MPEG
- M4A
- OGG
- WAV
Languages
The endpoint supports multiple languages. Thelang 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.
Latency
Requests for existing transcripts (eg. inmode=native) are resolved at normal latency. Requests that involve AI generation (eg. in mode=generate) can take up to 60s if they do not return an asynchronous job ID earlier. Long videos and large files take longer to transcribe.
Please consider this when implementing time-outs and UX in your project.
Pricing
- 1 existing transcript = 1 credit
- 1 generated transcript minute = 2 credits
Examples
| Case | Mode | What happens | Credits consumed |
|---|---|---|---|
| YouTube video without any transcript | auto | Supadata generates transcript with AI | 2 per min of video |
| Instagram video | native | No transcript available response (206) | 1 |
| Instagram video with existing transcript | auto | Supadata returns existing transcript | 1 |
| TikTok video | generate | Supadata generates transcript with AI | 2 per min of video (usually 2) |