Transcribe a file or a Twitch VOD

POST/v1/transcriptions1 credit

Have the speech of an audio or video file transcribed with timed cues: upload the file (multipart/form-data, field `file`, up to 99 MB), name one you already put in our storage (`upload_id` from Create an upload link: for files up to 2 GB), or name a Twitch past broadcast, highlight or upload (`url`). Send exactly one of the three. The answer is immediate: 202 with a `job_id`; the work (for a VOD: downloading its audio first) runs in the background and `GET /v1/transcriptions/{job_id}` tells its state and result. Our own route.

01Query parameters

Name	Type	Description
fileoptional	string	The audio or video file (anything ffmpeg reads: mp3, m4a, wav, ogg, mp4, mov, webm…), at most 99 MB and 3 hours long. Required unless `upload_id` or `url` is given.
upload_idoptional	string	Instead of `file`: the `upload_id` Create an upload link answered, after you PUT the file to its `upload_url`. For files over 99 MB (up to 2 GB), or to keep the file off this request. Also accepted in a JSON body or the query string.
file_nameoptional	string	The file's name shown in the job (`file_name`) when it comes by `upload_id`; `upload` when left out.
urloptional	string	Instead of `file`: a Twitch VOD, `https://www.twitch.tv/videos/<id>` (also `twitch.tv/<channel>/video/<id>`, `player.twitch.tv/?video=v<id>` or the bare id), at most 3 hours long. Also accepted in the query string or a JSON body `{"url": …, "language": …, "format": …}`. Only Twitch VODs for now.
languageoptional	string	ISO 639-1 code of the speech (e.g. `en`); left out, the language is detected.
formatoptional	string	The job's file format: `GET /v1/transcriptions/{job_id}?format=file` answers the finished transcript in it.Default: `json`Accepted values:`jsonsrtvtttext`

02Pricing

Reserved at the request from the recording's duration (the file's, or the VOD's length on Twitch): 1 credit up to 120 s, else 10 credits per started minute (a 10-minute VOD: 100, 3 hours: 1,800). Charged when the job completes with speech; a recording without speech, a failed or cancelled job (also a VOD whose download fails) and every refusal are free (the reservation is returned).

03Request

curl "https://api.scrapesocial.ai/v1/transcriptions" \
  -H "x-api-key: $SCRAPESOCIAL_KEY" \
  -F '[email protected]' \
  -F 'language=en' \
  -F 'format=srt'

04Responses

Real answers from the API. Lists are shortened to 2 items.

POST /v1/transcriptions{"file":"@interview.m4a","language":"en","format":"srt"}

{
  "success": true,
  "credits_remaining": 4980,
  "credits_charged": 0,
  "job_id": "8c51b6ab208c0f4c5fc98ea6740595a6",
  "status": "queued",
  "progress": 0,
  "created_at": "2026-10-25T17:13:48.300742Z",
  "started_at": null,
  "finished_at": null,
  "file_name": "interview.m4a",
  "file_bytes": 52955,
  "source_url": null,
  "duration_seconds": 6.277,
  "language": "en",
  "format": "srt",
  "credits_reserved": 1,
  "error": null,
  "status_url": "/v1/transcriptions/8c51b6ab208c0f4c5fc98ea6740595a6"
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

05Notes

202 answer: `job_id, status: queued, progress, created_at, started_at, finished_at, file_name, file_bytes, source_url, duration_seconds, language, format, credits_reserved, error, status_url`, with `credits_remaining` after the reservation and `credits_charged: 0`. For a Twitch VOD, `source_url` is its link (null for an uploaded file), `file_name` its title and `file_bytes` 0 until its audio is downloaded (then that audio's size); a 30-minute VOD is downloaded in about 8 s and transcribed in about a minute. Refusals, all free: 400 `missing_parameter` (none of file, upload_id and url), 400 `bad_request` (more than one, or a bad option), 404 `not_found` (an upload_id with no uploaded file: not PUT yet, its link expired, or already used: an upload makes one job), 400 `unsupported_platform` (a url that is not a Twitch VOD), 400 `invalid_file` (not audio or video, or no audio track), 400 `too_long` (over 3 hours), 404 `not_found` (unknown VOD), 403 `forbidden` (a VOD Twitch shows only to subscribers), 413 `file_too_large`, 402 `insufficient_credits` (the reservation does not fit). A finished job and its result are deleted 7 days after it finished.

06Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.