Create captions โ†’

Automation

Public API

Run video processing from your own code: access key, credits, job status and downloading the result in a chosen style.

Reading time: 6 min

What the API does

The public API repeats the editor workflow without the interface: you submit a video, the service transcribes the speech, aligns words, analyses the frame, writes headlines and composes styled subtitles, and you download the finished file.

  • Base URL โ€” https://api.captions.space/v1
  • Requests and responses are JSON.
  • The full pipeline runs once per video.

Access key

  1. Open the Developers section in your account.
  2. Create a key and copy it immediately.
  3. Send it in the Authorization: Bearer cs_live_โ€ฆ header.

Credits

Processing is paid for in credits: one credit covers one started minute of video. The API is unavailable on the Free plan; Pro includes 60 credits a month and the counter resets on the first day of the month.

  • A run reserves the plan's duration ceiling up front, then the charge is corrected to the real length of the video.
  • A failed run costs nothing โ€” the reservation is released.
  • Exporting files costs no credits: you pay for processing, not for every download.
  • The balance is visible in the Developers section and via GET /v1/me.

Starting a run

  1. POST /v1/videos with {"url": "โ€ฆ"} โ€” the run starts immediately.
  2. POST /v1/videos without a URL returns an upload_url: send the file with PUT.
  3. POST /v1/videos/{id}/start โ€” start processing an uploaded file.

Job status

The public API sends no email โ€” an integration learns the outcome by polling GET /v1/videos/{id}. The response carries status (awaiting_upload, processing, ready, failed), progress in percent, an error code and the actual credit charge.

  • Poll no more often than once every few seconds.
  • CPU processing takes minutes โ€” that is the normal duration, not a stall.

Downloading the result

  1. POST /v1/videos/{id}/exports with format: srt, vtt, ass, mp4, mov, hevc or webm.
  2. Pass style to rebuild the subtitles with another template.
  3. GET /v1/videos/{id}/exports returns the download link.

Response codes

  • 401 โ€” the key is missing, unknown or revoked.
  • 402 โ€” this month's credits are used up.
  • 403 โ€” the current plan has no API access.
  • 409 โ€” the video is not uploaded yet, already started, or not ready for export.
  • 422 โ€” unknown format, unknown style or a malformed URL.