Skip to main content

Transcriptions

Transcription converts a stored audio or video object into a transcript with word-level timings, segments, and speaker labels — the same data that drives captions in the editor.

It's a three-call flow: submit, poll, fetch the result. The result lives on a separate endpoint from the job because transcripts are large.

Over MCP the same work is one call: transcribe_asset waits for the transcript and returns it with ready-made SRT and VTT files.

Cost: 72 credits per hour of media, billed on the durationSeconds you declare and rounded up to whole credits. Ten minutes costs 12 credits.

The transcription job object​

FieldTypeDescription
idstringJob id (UUID).
statusenumqueued · running · succeeded · failed.
languagestring | nullDetected or requested language. null until known.
errorMessagestring | nullWhy it failed.
costCreditsnumber | nullCredits charged. null until it settles.
createdAtstringISO 8601.

POST /v1/transcriptions​

Submit a job. Returns immediately with status: "running".

Body

NameTypeRequiredDescription
storageIdstringyesA committed audio or video object. See Files.
durationSecondsnumberyesMedia length in seconds; must be positive. The charge is derived from this, not from the file — get it right.
languagestringnoBCP-47 hint, e.g. "en", "pt-BR". Omit to auto-detect.
projectIdstringnoBill to a shared project — the owner pays.

Returns { "job": TranscriptionJob }.

Request
curl -s -X POST https://api.corte.so/v1/transcriptions \
-H "Authorization: Bearer corte_sk_…" \
-H "Content-Type: application/json" \
-d '{
"storageId": "f2c94a67-0e1b-4d38-8b52-6a7f1c09e4d2",
"durationSeconds": 612
}'
Response
{
"job": {
"id": "6b0d3f28-91ae-4c57-b840-2f7c1e6a95d3",
"status": "running",
"language": null,
"errorMessage": null,
"costCredits": null,
"createdAt": "2026-07-28T18:02:19.615Z"
}
}

Errors

CodeWhen
invalid_paramsMissing storageId, non-positive durationSeconds, or an unknown/uncommitted object.
insufficient_credits · owner_insufficient_creditsBalance short of the 72-credits-per-hour cost. Nothing charged.
forbiddenTranscription is disabled for the workspace.

GET /v1/transcriptions/:id​

Poll the job. Only the submitter can read it.

Returns { "job": TranscriptionJob }.

Request
curl -s https://api.corte.so/v1/transcriptions/6b0d3f28-… \
-H "Authorization: Bearer corte_sk_…"
Response
{
"job": {
"id": "6b0d3f28-91ae-4c57-b840-2f7c1e6a95d3",
"status": "succeeded",
"language": "en",
"errorMessage": null,
"costCredits": 12,
"createdAt": "2026-07-28T18:02:19.615Z"
}
}

The transcript itself is not on the job — fetch it separately.


GET /v1/transcriptions/:id/result​

Fetch the transcript. Available only once status is succeeded; anything else is not_found (404), including a job that's still running.

Returns the transcript payload directly — not wrapped in a named key.

FieldTypeDescription
textstringThe full transcript as one string.
languagestringDetected or requested language.
wordsobject[]{ text, start?, end?, speaker? } — word-level timings in seconds. Drives karaoke-style captions.
segmentsobject[]{ text, start, end, speaker? } — sentence or utterance chunks. Drives subtitle blocks.
Request
curl -s https://api.corte.so/v1/transcriptions/6b0d3f28-…/result \
-H "Authorization: Bearer corte_sk_…"
Response
{
"text": "So the thing about exporting is that it's always free. No watermark, ever.",
"language": "en",
"words": [
{ "text": "So", "start": 0.12, "end": 0.28, "speaker": "A" },
{ "text": "the", "start": 0.28, "end": 0.39, "speaker": "A" },
{ "text": "thing", "start": 0.39, "end": 0.71, "speaker": "A" },
{ "text": "about", "start": 0.71, "end": 0.98, "speaker": "A" },
{ "text": "exporting", "start": 0.98, "end": 1.54, "speaker": "A" }
],
"segments": [
{ "text": "So the thing about exporting is that it's always free.", "start": 0.12, "end": 3.44, "speaker": "A" },
{ "text": "No watermark, ever.", "start": 3.61, "end": 4.88, "speaker": "A" }
]
}

speaker is present when the provider distinguished voices; it's a label like "A" / "B", not an identity.


Full flow​

import time, requests

BASE, HEAD = "https://api.corte.so", {"Authorization": f"Bearer {KEY}"}

def transcribe(storage_id, duration_seconds, language=None):
body = {"storageId": storage_id, "durationSeconds": duration_seconds}
if language:
body["language"] = language
job = requests.post(f"{BASE}/v1/transcriptions", json=body, headers=HEAD).json()["job"]

while job["status"] in ("queued", "running"):
time.sleep(3)
job = requests.get(f"{BASE}/v1/transcriptions/{job['id']}", headers=HEAD).json()["job"]

if job["status"] == "failed":
raise RuntimeError(job["errorMessage"])

return requests.get(f"{BASE}/v1/transcriptions/{job['id']}/result", headers=HEAD).json()