Transcript API

Submit a public media URL, track the asynchronous task, and retrieve structured transcripts, chapters, translations, SRT, and VTT files through one predictable API.

REST + JSON · UTF-8 · UTC / ISO 8601 · 200+ languages

Quickstart

A transcription request follows three steps. The API returns immediately while processing continues asynchronously.

Create a task with POST /transcriptions.
Poll the returned poll_url and honor retry_after.
Retrieve structured results and short-lived subtitle download URLs.

Authentication

Every OpenAPI request uses a Bearer API Key. Website cookies and login tokens are not accepted.

HTTP header

Authorization: Bearer $VT_API_KEY

Header	Required	Description
`Authorization`	Yes	Bearer API Key.
`Content-Type`	For POST	Must be `application/json`.
`Idempotency-Key`	For POST	Stable identifier for one logical create operation.
`X-Request-ID`	No	Client trace identifier echoed or generated by the server.

Idempotency

Use a stable Idempotency-Key for every logical create operation. This prevents network retries from creating duplicate billable tasks.

Request	Result
Same key and same body	Returns the original task with HTTP 200.
Same key and different body	Returns HTTP 409 `idempotency_conflict`.

Sources and formats

Provide a public HTTP or HTTPS URL. File upload is not supported by OpenAPI.

Source	Supported examples
Platforms	YouTube, TikTok, Instagram, Facebook, X, Bilibili
Cloud links	Google Drive, Dropbox
Direct files	MP3, MP4, M4A, WAV, WebM, MOV, AVI, OGG, AAC

Features and billing

Usage is calculated from rounded-up media duration:

billable_minutes = ceil(duration_seconds / 60)

Features	Description	Quota Usage
Transcribe	Full text, detected language, timed segments, and optional speakers.	1 API Quota / 1 Minute
YouTube, TikTok, Instagram, Facebook, X, Bilibili, Vimeo	Transcribe media directly from supported platform URLs.	Free (Limited Time Only)
Speaker Diarization	Identify and label different speakers in the transcript.	Free (Limited Time Only)
Language Detection	Automatically detect the source language.	Free (Limited Time Only)
Timestamps	Include timed segments for navigation and subtitle synchronization.	Free (Limited Time Only)
Subtitle (SRT/VTT)	Generate signed download URLs for SRT and VTT subtitle files.	Free (Limited Time Only)
Chapters	Generate ordered chapter ranges with titles and summaries.	1 API Quota / 1 Minute
Translation	Generate translated full text and aligned segments.	1 API Quota / 1 Minute

Task lifecycle

queuedprocessingsucceededpartial_succeededfailedcancelled

Create transcription

POST/transcriptions

Create an asynchronous transcription task from a public media URL.

Field	Type	Required	Description
`source_url`	string	Yes	Public media or supported platform URL.
`language`	string	No	Source language code; defaults to automatic detection.
`speaker_diarization`	boolean	No	Detect speakers when supported.
`features.chapters`	boolean	No	Generate chapters.
`features.translation`	object	No	Enable translation when present.

cURL

curl --request POST "https://videotranscriber.ai/openapi/v1/transcriptions" \
  --header "Authorization: Bearer $VT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: transcribe-order-0001" \
  --data '{
    "source_url": "https://example.com/media/demo.mp4",
    "language": "auto",
    "speaker_diarization": true,
    "features": {
      "chapters": true,
      "translation": {"target_language": "es"}
    }
  }'

Response

{
  "request_id": "tr_01JEXAMPLE",
  "status": "queued",
  "poll_url": "/transcriptions/tr_01JEXAMPLE",
  "retry_after": 5
}

Get transcription

GET/transcriptions/{request_id}

Get task status, feature-level status, usage, errors, and result availability.

cURL

curl --request GET \
  "https://videotranscriber.ai/openapi/v1/transcriptions/$REQUEST_ID" \
  --header "Authorization: Bearer $VT_API_KEY"

Get result

GET/transcriptions/{request_id}/result

Retrieve structured results for successful features and signed download URLs for SRT and VTT files.

cURL

curl --request GET \
  "https://videotranscriber.ai/openapi/v1/transcriptions/$REQUEST_ID/result" \
  --header "Authorization: Bearer $VT_API_KEY"

Response schemas

JSON is UTF-8. Timeline values use seconds and may contain decimals. Clients must ignore unknown response fields.

Schema	Contents
Transcript	Detected language, full text, duration, timed segments, and optional speakers.
Chapters	Ordered ranges with start, end, title, and summary.
Translation	Source and target language, translated text, and aligned segments.

The speaker field is null when diarization is disabled or the provider does not return a reliable speaker label.

Errors

Request-level failures use HTTP status codes and a stable English error.code. Do not branch on error.message.

Error response

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "retryable": false
  },
  "request_id": "req_01JEXAMPLE"
}

HTTP status	Meaning
400	Invalid request or unsupported input.
401	Missing or invalid API Key.
409	Idempotency conflict.
429	Rate or quota limit reached.
500 / 503	Temporary server or provider failure.

Limits and retries

Honor rate-limit and retry headers returned by the API:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After

Retention and security

Resource	Retention
Results	Available for 30 days from result generation.
Download URLs	Private, signed, and valid for up to one hour.
Task records	Kept for the creation month and the following calendar month in UTC.