Quickstart

1. Create an API key

Sign in, open API keys, and create a key with the transcripts scope. Copy the value when it is shown; the full key is not displayed again.

API keys use the tr_ prefix and are available on paid accounts. Keep the key in a server-side secret store rather than browser code or a public repository.

2. Request a transcript

Send a public media URL to the versioned endpoint:

curl --request POST 'https://api.transcript.im/v1/transcript' \
  --header 'Authorization: Bearer tr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en,asr",
    "format": "json",
    "includeTimestamp": true,
    "sendMetadata": true
  }'

When a matching caption track or cached result exists, the API responds with 200 and a transcript:

{
  "status": "success",
  "format": "json",
  "transcript": {
    "id": "7d2c9e30-5b58-4f4b-a1bf-918fd15ddf12",
    "platform": "youtube",
    "externalId": "dQw4w9WgXcQ",
    "lang": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 18.2, "duration": 3.1 }
    ]
  },
  "cached": false,
  "language": "en",
  "metadataStatus": "complete",
  "lengthSeconds": 213
}

metadataStatus reports how complete the requested metadata is (complete, partial, pending, or unavailable) without holding the transcript result back. With format: "text" the response carries a text string instead of transcript segments.

To transcribe a local media file instead of a URL, send the same endpoint a multipart/form-data body with a file field plus the same options. Uploads are account-only and are handed to the same asynchronous pipeline.

3. Handle asynchronous transcription

If the source has no usable captions (or an asr entry is reached), the API starts speech recognition and responds with 202:

{
  "status": "pending",
  "jobId": "9f065d89-e8c9-48ec-b42a-a87c63d0e6ab",
  "stage": "asr_queued"
}

Poll the job with the same credential:

curl 'https://api.transcript.im/v1/transcript/job/9f065d89-e8c9-48ec-b42a-a87c63d0e6ab' \
  --header 'Authorization: Bearer tr_your_api_key'

Continue until the job reports success or failed. Use a delay and exponential backoff between polls; do not treat the initial 202 as an error. Instead of polling, you can subscribe to GET /v1/transcript/job/{id}/events (Server-Sent Events); the stream always sends a snapshot first, then stage updates, then a terminal completed or failed.

Account submits can be retried safely: send an Idempotency-Key header on POST /v1/transcript, and the same key plus the same request identity returns the existing job instead of starting a second extraction; the same key with a different identity returns 409 IDEMPOTENCY_CONFLICT. The identity covers the owner, platform, external id, language list, ASR intent, format, and timestamp/metadata options. Current limits to know: guest retries do not have Idempotency-Key guarantees, and a multipart upload mints a new upload id on every request, so the header does not make a duplicate file reusable.

A guest (no credential) can submit one public video to the same endpoint; it is attributed to a per-browser tgs cookie and limited to the guest daily allowance. Uploads, batches, and exports require an account.

Next steps

• Read Authentication before shipping the key in production.
• See Transcript workflows for language priority, batches, and pagination.
• Open the POST /v1/transcript reference for the complete schema.