Create a transcription

Create a transcription with POST /transcriptions. Pick the path that matches where your media lives — provide exactly one of url or storagePath:

Your media is…	Use	Field
Already at a public `https` URL (CDN, public bucket, …)	Option A — from a URL	`url`
A local or private file you need to upload to us first	Option B — upload to our storage	`storagePath`

The call returns immediately with a job id and status: "pending". The transcription runs asynchronously — see Retrieve results and Webhooks.

Option A — from a URL

The simplest path when your file is already publicly reachable. Hand us a public https URL and we fetch the bytes directly — you don't upload anything.

curl -X POST https://www.transcribevideototext.com/api/v1/transcriptions \
  -H "Authorization: Bearer vtt_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/podcast.mp3",
    "language": "auto",
    "diarize": true
  }'

The URL must use https and resolve to a public host (private/loopback addresses are rejected).

Option B — upload to our storage

For local or private files, upload to our Cloudflare R2 bucket with a signed URL, then create the job from the returned path. We fetch it from storage for you — you never deal with a download URL.

Get a signed upload URL

POST /uploads returns two things: a short path (the object key) and a long signedUrl (where you upload the bytes).

curl -X POST https://www.transcribevideototext.com/api/v1/uploads \
  -H "Authorization: Bearer vtt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"interview.mp3","contentType":"audio/mpeg"}'

{
  "path": "9dd87f30-c8d2-4779-ae9d-01dd4c323936.mp3",
  "signedUrl": "https://…r2.cloudflarestorage.com/…?X-Amz-Signature=…"
}

Upload the file to `signedUrl`

PUT the raw bytes to the signedUrl (it expires in 1 hour). Don't send your API key on this request — the signed URL authenticates itself.

curl -X PUT "<signedUrl>" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @interview.mp3

Create the transcription with `path`

Pass the short path from step 1 as storagePath.

curl -X POST https://www.transcribevideototext.com/api/v1/transcriptions \
  -H "Authorization: Bearer vtt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"storagePath":"9dd87f30-c8d2-4779-ae9d-01dd4c323936.mp3","fileName":"interview.mp3"}'

storagePath is the path value (a short key like 9dd87f30-…mp3) — not the signedUrl. Passing the URL returns 422 invalid_request.

Options

Field	Type	Description
`language`	string	ISO 639-1 code (see Supported languages) or `auto` (default).
`diarize`	boolean	Separate speakers.
`fileName`	string	Display name (derived from the URL if omitted).
`mediaType`	string	MIME type hint.

Supported languages

Pass language as one of the ISO 639-1 codes below, or omit it (or send auto) to auto-detect the spoken language.

Language	Code	Language	Code	Language	Code
Arabic	`ar`	German	`de`	Polish	`pl`
Azerbaijani	`az`	Greek	`el`	Portuguese	`pt`
Bosnian	`bs`	Hebrew	`he`	Romanian	`ro`
Bulgarian	`bg`	Hindi	`hi`	Russian	`ru`
Cantonese	`yue`	Hungarian	`hu`	Serbian	`sr`
Catalan	`ca`	Indonesian	`id`	Slovak	`sk`
Chinese	`zh`	Italian	`it`	Slovenian	`sl`
Croatian	`hr`	Japanese	`ja`	Spanish	`es`
Czech	`cs`	Korean	`ko`	Swedish	`sv`
Danish	`da`	Latvian	`lv`	Thai	`th`
Dutch	`nl`	Lithuanian	`lt`	Turkish	`tr`
English	`en`	Macedonian	`mk`	Ukrainian	`uk`
Estonian	`et`	Malay	`ms`	Urdu	`ur`
Finnish	`fi`	Norwegian	`no`	Vietnamese	`vi`
French	`fr`	Galician	`gl`

Idempotency

Send an Idempotency-Key header so a retried request returns the same job instead of creating a duplicate — important for automated retries.

curl -X POST https://www.transcribevideototext.com/api/v1/transcriptions \
  -H "Authorization: Bearer vtt_your_key" \
  -H "Idempotency-Key: my-unique-id-123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/podcast.mp3"}'

Create a transcription

On this page