REST endpoint

Prepare a direct upload

Send file metadata before transferring bytes. Fast Transcriber validates the account, media type, and file-size allowance, then returns either one presigned PUT target or a set of multipart part URLs.

POST/api/v1/uploads200 OK

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
`filename`required	string	Original filename, up to 240 characters.
`size`required	integer	Exact file size in bytes; must be greater than zero.
`content_type`	string \| null	MIME type when known, such as audio/mpeg.
`speaker_diarization`	boolean	Preflight the Pro-only speaker diarization requirement. Defaults to false.

curl --request POST https://fast-transcriber.com/api/v1/uploads \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "interview.mp3",
    "content_type": "audio/mpeg",
    "size": 1234567
  }'

200 OK

Response

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

Field	Type	Description
`data.key`	string	Account-scoped object key used when queueing the job.
`data.storage`	r2 \| wasabi	Storage provider. Return it unchanged in later requests.
`data.content_type`	string	Validated media MIME type.
`data.upload.type`	single \| multipart	Selects the byte-transfer workflow.
`data.upload.headers`	object	Single upload only: headers to copy to the storage request.
`data.upload.method`	PUT	Single upload only: HTTP method for the storage request.
`data.upload.url`	string	Presigned PUT URL for a single upload.
`data.upload.parts`	array	Ordered presigned part URLs for a multipart upload.
`data.upload.parts[].part_number`	integer	Multipart only: positive number identifying this part.
`data.upload.parts[].url`	string	Multipart only: presigned PUT URL for this part.
`data.upload.part_size`	integer	Multipart only: byte size for each part except the final part.
`data.upload.upload_id`	string	Multipart only: identifier required to complete or abort the upload.

{
  "data": {
    "content_type": "audio/mpeg",
    "key": "transcriptions/user_…/interview.mp3",
    "storage": "r2",
    "upload": {
      "headers": { "content-type": "audio/mpeg" },
      "method": "PUT",
      "type": "single",
      "url": "https://storage.example/presigned-target"
    }
  }
}

{
  "data": {
    "content_type": "video/mp4",
    "key": "transcriptions/user_…/recording.mp4",
    "storage": "r2",
    "upload": {
      "part_size": 16777216,
      "parts": [
        {
          "part_number": 1,
          "url": "https://storage.example/presigned-part-1"
        }
      ],
      "type": "multipart",
      "upload_id": "upload_…"
    }
  }
}

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_upload`	filename and a positive byte size are required.
413	`file_too_large`	The declared size is above the account's file limit.
415	`unsupported_type`	The filename or MIME type is not accepted audio or video.
503	`api_uploads_unavailable`	The upload backend is temporarily unavailable.

{
  "error": {
    "code": "invalid_upload",
    "message": "filename and a positive size are required."
  }
}

Production guidance

Implementation notes

Upload the file bytes to the returned storage URL, not to fast-transcriber.com.
Keep key, storage, filename, size, and content_type for the create-transcription request.
The maximum accepted size comes from the authenticated account plan.
Single-upload URLs expire after 15 minutes; multipart part URLs expire after four hours.
For multipart uploads, use the returned part_size for every part except the final part. R2 currently returns 16 MiB.