Guides

Large Files (Two-Step Upload)

Sending files directly to the transcription endpoint works well for short clips, but the platform strictly limits direct request bodies to 4 MB.

To transcribe files up to 25 MB, you must use the two-step upload flow. This allows you to upload the file directly to our storage layer, bypassing the 4 MB limit, and then pass the file's ID to the transcription endpoint.

Step 1 — Request an upload URL

Tell the API about the file you want to upload. You must provide the exact size and MIME type.

curl -X POST https://api.quantclarity.com/v1/files \
-H "Authorization: Bearer qc_live_REPLACE_WITH_KEY" \
-H "Content-Type: application/json" \
-d '{
    "filename": "interview.mp3",
    "content_type": "audio/mpeg",
    "size_bytes": 14500000
}'

The API responds with a secure, pre-signed upload URL and a file_... ID.

{
"id": "file_12345678-1234-1234-1234-123456789abc",
"upload_url": "https://[project].supabase.co/storage/v1/object/sign/audio-uploads/...",
"content_type": "audio/mpeg",
"expires_at": "2026-10-06T12:00:00.000Z"
}

Step 2 — Upload the file bytes

Send a PUT request directly to the upload_url with the raw file bytes. Set the Content-Type header to the content_type value returned in Step 1.

curl -X PUT "https://[project].supabase.co/storage/v1/object/sign/audio-uploads/..." \
-H "Content-Type: audio/mpeg" \
--data-binary "@interview.mp3"

A successful upload returns 200 OK.

Step 3 — Start the transcription

Now you can call the transcription endpoints just like normal, but instead of sending the file bytes (file=@...), you send the ID you got in Step 1 (file_id=file_...).

curl https://api.quantclarity.com/v1/audio/transcriptions \
-H "Authorization: Bearer qc_live_REPLACE_WITH_KEY" \
-F "file_id=file_12345678-1234-1234-1234-123456789abc" \
-F "model=auto"

This works exactly the same for both the synchronous endpoint (/v1/audio/transcriptions) and the asynchronous endpoint (/v1/transcriptions).