The Turnscribe API lets you transcribe audio/video from a URL or an uploaded file, and check the status of a transcription job. All endpoints are versioned under /api/v1/ and require an API key. You can generate a key from your dashboard once you sign up or log in.

Base URL

https://turnscribe.com/api/v1/

Authentication

Every request must include your API key in the Authorization header, using the Api-Key scheme:

Authorization: Api-Key <your_api_key>

Requests with a missing or invalid key return 400 Bad Request:

{
  "error": "Invalid API key. See https://turnscribe.com/api for more information. Contact us at [email protected] if you have any questions or need an increase in your limit."
}

Limits

Audio duration (URL requests): Each API key has a maximum duration per request (15 minutes by default). Requests for longer media are rejected before processing.
File uploads: Maximum file size of 50MB by default.
Allowed file extensions — audio: .mp3, .wav, .ogg, .flac, .aac, .m4a, .wma, .opus
Allowed file extensions — video: .mp4, .mkv, .webm, .avi, .mov, .flv, .wmv, .mpeg, .mpg, .3gp, .ts, .m2ts, .mts, .vob, .ogv, .rm, .rmvb

Need a higher duration limit? Contact [email protected].

1. Transcribe from a URL

POST /api/v1/transcribe/

Submits a YouTube, TikTok, Facebook or other media URL for transcription. If the same URL was already transcribed, the cached result is returned immediately.

Body (JSON)

{
  "url": "https://www.youtube.com/watch?v=..."
}

Response — 202 Accepted (new job queued)

{
  "status": "PENDING",
  "transcript_id": "...",
  "task_id": "..."
}

Response — 200 OK (already cached)

{
  "status": "COMPLETED",
  "transcript_id": "...",
  "content": "...",
  "title": "..."
}

Response — 400 Bad Request (duration exceeds your key's limit)

{
  "error": "Audio duration (32.4 min) exceeds the allowed limit of 15 minutes for your API key.",
  "media_duration_minutes": 32.4,
  "api_key_max_minutes": 15,
  "url": "https://www.youtube.com/watch?v=...",
  "message": "Your API key has a limit of 15 minutes of URLs per request. To transcribe longer audio, please for now contact us to request an increase in your limit at [email protected]."
}

Example — curl

curl -X POST https://turnscribe.com/api/v1/transcribe/ \
  -H "Authorization: Api-Key <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=..."}'

2. Transcribe from an uploaded file

POST /api/v1/transcribe/file/

Uploads an audio or video file directly (multipart/form-data) instead of a URL.

Form field

file — the audio/video file to transcribe (see allowed extensions and size limit above)

Response — 202 Accepted

{
  "status": "PENDING",
  "transcript_id": "...",
  "task_id": "..."
}

Possible errors

400 — {"error": "File is required"}
400 — {"error": "Invalid file extension"}
400 — {"error": "Invalid file size. Max 50MB"}
400 — {"error": "Error processing file"}

Example — curl

curl -X POST https://turnscribe.com/api/v1/transcribe/file/ \
  -H "Authorization: Api-Key <your_api_key>" \
  -F "file=@/path/to/audio.mp3"

3. Bulk transcribe from URLs Premium

POST /api/v1/transcribe/bulk/

Submits up to several URLs in a single request. Requires an API key linked to an account on a plan that includes bulk URL import (Premium); the exact limit is returned in the error message if you go over it.

Body (JSON)

{
  "urls": [
    "https://www.youtube.com/watch?v=...",
    "https://www.tiktok.com/@user/video/..."
  ]
}

Response — 202 Accepted

{
  "results": [
    { "url": "...", "status": "PENDING", "transcript_id": "...", "task_id": "..." },
    { "url": "...", "status": "COMPLETED", "transcript_id": "...", "content": "...", "title": "..." },
    { "url": "...", "error": "..." }
  ]
}

Each item in results mirrors the response of the single-URL endpoint above: PENDING for a newly queued job, COMPLETED if you already have your own transcript of that URL, or error if that particular URL was rejected. Poll each transcript_id/task_id with the status endpoint below.

Possible errors

400 — {"error": "urls (a list of URLs) is required"}
400 — {"error": "You can only submit up to 10 URLs at once."}
403 — {"error": "Your plan does not include bulk URL import. Please upgrade your plan."}
403 — {"error": "Bulk URL import requires an API key linked to a Premium account."}

Example — curl

curl -X POST https://turnscribe.com/api/v1/transcribe/bulk/ \
  -H "Authorization: Api-Key <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.youtube.com/watch?v=...", "https://www.tiktok.com/@user/video/..."]}'

4. Check transcription status

GET /api/v1/transcribe/status/

Polls the status of a job created by either endpoint above.

Query parameters

transcript_id — required, returned when the job was created
task_id — returned when the job was created (echoed back while pending)

Response — pending

{
  "status": "PENDING",
  "transcript_id": "...",
  "task_id": "..."
}

Response — completed

{
  "status": "COMPLETED",
  "transcript_id": "...",
  "content": "...",
  "title": "..."
}

Response — error

{
  "status": "ERROR",
  "transcript_id": "...",
  "content": "..."
}

Other errors

400 — {"error": "transcript_id is required"}
404 — {"error": "Transcript not found"}

Example — curl

curl -X GET "https://turnscribe.com/api/v1/transcribe/status/?transcript_id=...&task_id=..." \
  -H "Authorization: Api-Key <your_api_key>"

Questions or need a higher limit? Reach out at [email protected].

API Documentation

Base URL

Authentication

Limits

1. Transcribe from a URL

2. Transcribe from an uploaded file

3. Bulk transcribe from URLs Premium

4. Check transcription status