REST endpoint

Create a transcription

Provide exactly one source: source_url for supported public media, or upload for a completed direct upload. The API returns immediately with a job ID and a Location header for polling.

POST/api/v1/transcriptions202 Accepted

Use this endpoint OpenAPI spec

Authentication

Send an active Fast Transcriber API key as an HTTP bearer token.

Authorization: Bearer ft_live_replace_me

Input

Request

Use the fields below and send a JSON body.

Field	Type	Description
`source_url`	uri	Conditionally required: provide this public HTTP(S) media URL or upload, but not both.
`upload`	object	Conditionally required: provide this completed upload reference or source_url, but not both.
`upload.filename`	string	Required with upload: original filename.
`upload.key`	string	Required with upload: owned object key from prepare-upload.
`upload.size`	integer	Required with upload: exact uploaded byte size.
`upload.storage`	r2 \| wasabi	Required with upload: storage provider returned by prepare-upload.
`upload.content_type`	string \| null	Media MIME type when known.
`speaker_diarization`	boolean	Identify speakers on Pro. Defaults to false.

curl --include --request POST https://fast-transcriber.com/api/v1/transcriptions \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "source_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "speaker_diarization": false
  }'

202 Accepted

Response

Successful JSON responses use a top-level data envelope. A 204 response has no body.

Field	Type	Description
`Location header`	string	Relative polling URL for this job.
`data.id`	uuid	Transcription job ID.
`data.filename`	string	Derived link label or uploaded filename.
`data.status`	string	Initial processing status.
`data.created_at`	date-time	UTC job creation time.

{
  "data": {
    "created_at": "2026-09-03T10:12:00.000Z",
    "filename": "youtube.com-link.mp3",
    "id": "95c3fdd8-…",
    "status": "processing"
  }
}

Stable envelope

Errors

API errors return a machine-readable code and message.

Status	Code	Meaning
401	`missing_api_key`	No bearer key was supplied.
401	`invalid_api_key`	The bearer key is malformed, unknown, or revoked.
403	`pro_required`	Speaker diarization was requested without a Pro account.
429	`daily_limit_reached`	The account has reached its daily transcription allowance.
400	`invalid_request`	The request body is not a JSON object.
400	`invalid_source`	The body contains both source types or neither one.
400	`invalid_source_url`	source_url is not a valid HTTP(S) URL.
400	`invalid_upload`	The upload reference is missing a required field or has an invalid value.
400	`empty_upload`	The stored upload contains no bytes.
403	`upload_not_owned`	The upload key belongs to another account.
404	`upload_not_found`	The prepared upload no longer exists.
413	`file_too_large`	The stored upload is above the account's file limit.
415	`unsupported_type`	The uploaded object is not an accepted audio or video type.
503	`api_processing_unavailable`	The transcription processing backend is unavailable.
503	`queue_unavailable`	The processing job could not be queued.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body must be a JSON object."
  }
}

Production guidance

Implementation notes

A 202 response means the job was queued, not that transcription is complete.
Poll the Location header until status is completed or failed.
source_url supports public YouTube, Instagram, TikTok, Facebook, Google Drive, and direct media URLs.