Skip to content
Try it free

API

API quickstart

Create a job, wait for it, and read the Context, in curl, TypeScript and Python. Then stream progress and upload a file.

View as Markdown
On this page

You need an API key. Keys are made in the dashboard, after you sign in. See API authentication. To check that the API is up first, run curl https://scribiz.com/api/v1/status. It needs no key.

Terminal
export SCRIBIZ_API_KEY=sbz_live_your_key_here

The examples use a 19 second public YouTube video, so they cost almost nothing.

Create a job and read the Context

JOB=$(curl -s https://scribiz.com/api/v1/context \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: $(uuidgen)" \  -d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw", "mode": "auto"}' | jq -r .job_id)while true; do  STATE=$(curl -s "https://scribiz.com/api/v1/jobs/$JOB" -H "Authorization: Bearer $SCRIBIZ_API_KEY")  STATUS=$(printf '%s' "$STATE" | jq -r .status)  case "$STATUS" in    succeeded) break ;;    failed|canceled) printf '%s' "$STATE" | jq .error; exit 1 ;;  esac  sleep 3doneprintf '%s' "$STATE" | jq '.result.synthesis.summary.tldr'
Output
The speaker stands in front of elephants and points out that they have very long trunks.

What you get back is the Context. Its fields are in The Context object.

Three things the examples do on purpose:

  • They send an Idempotency-Key, so a retry after a network error does not start a second job or charge twice.
  • They poll every three seconds. A job that is still queued or running is not an error.
  • They stop on failed and canceled, and show error, which has a code and a hint. See Errors and limits.

result is null while the job runs, and synthesis can be null if the summary step did not run, so check before you read into it. The curl example uses printf '%s' rather than echo on purpose: echo in zsh turns the \n inside the JSON into real line breaks, and jq then refuses the text.

Watch progress

The job's event stream sends one event as the work happens. It is optional. GET /v1/jobs/:id is always enough.

Terminal
curl -N "https://scribiz.com/api/v1/jobs/$JOB/events" \  -H "Authorization: Bearer $SCRIBIZ_API_KEY"
Server-sent events
retry: 3000id: 1event: queueddata: {"runId":"job_2DUafpGltJTqVKlAYlIREm","t":0,"type":"queued"}id: 2event: starteddata: {"attempt":1,"runId":"job_2DUafpGltJTqVKlAYlIREm","t":0,"type":"started"}id: 3event: startdata: {"input":"https://www.youtube.com/watch?v=jNQXAC9IVRw","mode":"auto","type":"start","runId":"d6c4e6fe","t":0}id: 11event: stagedata: {"detail":"manual en captions, 6 segments","ms":5472,"stage":"download","status":"done","type":"stage","runId":"d6c4e6fe","t":5476}...id: 17event: donedata: {"summary":{"durationSeconds":19,"ms":8197,"usd":0.0017175,"words":39},"type":"done","runId":"d6c4e6fe","t":8197}

Each data: line is a JSON event, the same ones the CLI prints with --json, plus queued, started and requeued from the API. See The JSON protocol. The id: lets you resume: reconnect with a Last-Event-ID header, or ?last_event_id=, and the stream continues after that event. A line that starts with : is a keep-alive. The stream ends after the job is done or has failed.

Upload a file

Upload the file first, then create the job from the upload. The API takes audio and video files, up to 100 MB. A video upload sends the whole file to Scribiz. To send only the sound, extract the audio first:

Terminal
ffmpeg -i talk.mp4 -vn -ac 1 -ar 16000 -b:a 48k talk.mp3
Terminal
UPLOAD=$(curl -s -X PUT https://scribiz.com/api/v1/uploads \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: audio/mpeg" \  -H "X-File-Name: talk.mp3" \  --data-binary @talk.mp3 | jq -r .upload_id)curl https://scribiz.com/api/v1/context \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: application/json" \  -d "{\"upload_id\": \"$UPLOAD\", \"mode\": \"audio\"}"
201 Created, from PUT /v1/uploads
{  "bytes": 73264,  "duration_seconds": 12.120726,  "expires_at": 1791097083297,  "file_name": "speech.mp3",  "has_audio": true,  "has_video": false,  "mime": "audio/mpeg",  "upload_id": "upl_4dEjVvJnlzplZvFcA2PULr"}

An upload is kept for one hour, belongs to one job, and is removed when that job succeeds. A file with no audio track, such as a screen recording, works with "mode": "visual". For anything over 100 MB, cut the audio first with ffmpeg as above. Or use the CLI, which cuts the audio on your machine and reads it with your own Gemini key or your Scribiz account.

Next

Checked against the Scribiz build on 2026-10-05.

Loading the index