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 code or `auto` (default).
`diarize`	boolean	Separate speakers.
`fileName`	string	Display name (derived from the URL if omitted).
`mediaType`	string	MIME type hint.

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"}'