videocaption.io
Caption my videos
Last changed 8 September 2026

API

Everything the site does, as HTTP: upload a clip, read and correct its transcript, set the look, render, download. JSON in and out, one key per account, the same credits as the site.

Base URLhttps://videocaption.io/api/v1
Your key

Sign in with your e-mail address and the key appears here. Keys are tied to the account and spend its credits.

Sign in

Authentication

Send the key as a bearer token on every request. Cookies are ignored under /api/v1.

curl https://videocaption.io/api/v1/account \
  -H "Authorization: Bearer vc_live_…"

A missing or revoked key answers 401. Keep the key on your server; it can spend your credits.

The flow

  1. 01
    Upload a clip. Transcription starts by itself; the video goes uploaded → transcribing → ready.
  2. 02
    Read the words, fix the text if needed, trim the window.
  3. 03
    Set the look once per account, or check a still of any look on the real frame, free.
  4. 04
    Render: 5 credits per started 2 minutes of the trimmed clip (the video's credits says the exact number), taken when the render starts and returned if it fails on our side. queued → rendering → done.
  5. 05
    Download within 48 hours; then the file is gone. The row itself is removed 7 days after the upload.

Videos

POST/videosUpload
curl -X POST https://videocaption.io/api/v1/videos \
  -H "Authorization: Bearer vc_live_…" \
  -F file=@clip.mp4

MP4 or MOV, up to 20 minutes each, one file per request. Answers 201 with the video document.

GET/videos · /videos/:idList and read
curl https://videocaption.io/api/v1/videos -H "Authorization: Bearer vc_live_…"
curl https://videocaption.io/api/v1/videos/vid_… -H "Authorization: Bearer vc_live_…"

Reading also brings the status up to date, so poll the video until it is ready, and after a render until it is done. Every few seconds is plenty.

The video document

{
  "id": "vid_…", "filename": "clip.mp4", "status": "ready",
  "seconds": 32.9, "width": 1080, "height": 1920, "size": 41234567,
  "trimStart": 0, "trimEnd": null,
  "wordCount": 70, "text": "Meet the new …",
  "words": [{ "text": "Meet", "start": 0.21, "end": 0.48 }, …],
  "previewReady": false, "error": null,
  "credits": 5, "creditsCharged": 0, "expiresAt": null, "downloadUrl": null,
  "subtitlesUnlocked": false, "subtitlesUrl": null,
  "createdAt": "…", "updatedAt": "…"
}

Statuses: uploaded, transcribing, ready, previewing, queued, rendering, done, failed. A failed video carries the reason in error and costs nothing.

PATCH/videos/:idCorrect the text, trim
curl -X PATCH https://videocaption.io/api/v1/videos/vid_… \
  -H "Authorization: Bearer vc_live_…" -H "Content-Type: application/json" \
  -d '{ "text": "Meet the new collection.", "trimStart": 1.5, "trimEnd": 20 }'

Send any of the three. The corrected text keeps the old timings word for word when the count matches, and spreads them otherwise. trimEnd: null means the end of the clip.

POST/videos/:id/renderRender
curl -X POST https://videocaption.io/api/v1/videos/vid_…/render -H "Authorization: Bearer vc_live_…"

Uses the account's style and costs the video's credits. Answers 202 with the video, or 402 with needed and available when the credits are short. Rendering a finished video again costs the same again; a failed one is put back in line first.

GET/videos/:id/downloadDownload
curl -L -o captioned.mp4 https://videocaption.io/api/v1/videos/vid_…/download -H "Authorization: Bearer vc_live_…"

The MP4, with range requests. ?sample=1 gives the free twenty-second sample once previewReady is true; ask for one with POST …/sample.

GET/videos/:id/subtitlesSRT, VTT
curl -L -o clip.srt https://videocaption.io/api/v1/videos/vid_…/subtitles -H "Authorization: Bearer vc_live_…"
curl -L -o clip.vtt "https://videocaption.io/api/v1/videos/vid_…/subtitles?format=vtt" -H "Authorization: Bearer vc_live_…"

The subtitle file of the trimmed clip, its cues grouped as the captions are. A finished render includes it; on its own it costs 5 credits, whatever the length: POST …/subtitles pays once, then subtitlesUnlocked is true and the GET answers. Before that the GET answers 402 with subtitles_locked.

DELETE/videos/:idRemove
curl -X DELETE https://videocaption.io/api/v1/videos/vid_… -H "Authorization: Bearer vc_live_…"

Style

One style per account, used by every render. Read it with GET /style, replace it with PUT /style:

curl -X PUT https://videocaption.io/api/v1/style \
  -H "Authorization: Bearer vc_live_…" -H "Content-Type: application/json" \
  -d '{ "style": "punch", "placement": "bottom", "size": "normal",
        "highlight": true, "highlightColor": "#cde73f",
        "highlightShape": "color", "mode": "line" }'
FieldValues
styletemplate, mono, boxed, sans, light, inverse, soft, punch, minimal, outline
placementtop, center, bottom
sizesmall, normal, large
highlighttrue to light the spoken word, false for a plain line
highlightColor#rrggbb
highlightShapecolor (the word painted), fill (a plate behind it), underline
modeline (short lines, a new one after every sentence), word (one word at a time)
caseupper, lower, asis (as written); absent means the look's own rule: template, punch and outline set uppercase, mono and minimal lowercase
GET/videos/:id/stillA still, to compare looks
curl -o still.jpg "https://videocaption.io/api/v1/videos/vid_…/still?style=mono&shape=underline&color=%235ec8ff" \
  -H "Authorization: Bearer vc_live_…"

One frame of the clip with its caption drawn by the render itself, in the account's style or the one in the query (style, placement, size, highlight, color, shape, mode, case). Free, about a second. The headers X-Caption-At and X-Caption-Line say which second and which words.

Account

curl https://videocaption.io/api/v1/account -H "Authorization: Bearer vc_live_…"

Your e-mail, the balance, the pricing rule (creditStep per blockSeconds) and the current style. Credits are bought on the site; there is no endpoint for that.

Errors

Every failure is JSON: { "error": { "code": "…", "message": "…" } }.

401
unauthorized
404
not_found
400 · 409
refused
The message says why, for instance a transcript that is not ready yet.
402
insufficient_credits
400
invalid_request
With issues naming the field.
400
invalid_json
400
invalid_upload
400
invalid_text
400
invalid_trim
413
too_large
The upload is over the size limit.
429
rate_limited
502
upstream
The render backend answered badly; try again.
500
internal

Limits

Clips up to 20 minutes. Uploads count against the same allowances as the site. There is no fixed rate limit today; keep polling to every few seconds and batch what you can. The terms apply to the API as they do to the site.