Public API

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 callouts 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 balance is shared with your account: minutes spent in the editor come off the same balance. The API is unavailable on the Free plan; Pro includes 1000 credits per 30-day subscription period, renewing on the day you renew rather than on the 1st.

• A run reserves the plan's duration ceiling up front, but never more than the balance left; the charge is then corrected to the real length of the video. A video longer than the remaining balance covers fails with credits_exhausted.
• 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 your account, in the Developers section and via GET /v1/me.

Starting a run

1. POST /v1/videos with {"url": "…"} pointing to a video file or a YouTube video — the run starts immediately.
2. POST /v1/videos without a URL returns an upload_url: send the file with PUT (the link is valid for an hour).
3. If PUT to the storage is blocked on your network, upload through the API itself: POST /v1/videos/{id}/file with a multipart field named file.
4. POST /v1/videos/{id}/start — start processing an uploaded file.

Videos and reference data

• GET /v1/videos — videos in the account, newest first; limit goes up to 200 (50 by default).
• DELETE /v1/videos/{id} — delete a video and its files. Credits already charged are not refunded.
• GET /v1/styles — design templates: the id for the style field and a name.
• GET /v1/formats — export formats, their file extensions and kind (video or subtitles).
• GET /v1/me — plan, credit allowance and what is left.

API and the editor

Videos created through the API live in your account: open any of them in the editor to fix a word or a timing, add text templates or your own watermark. The next video file you order through the API comes with that design — the server builds the frame from the same edits as the editor.

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 — the credits for this period are used up.
• 403 — the current plan has no API access.
• 404 — the video does not exist or belongs to another account.
• 409 — the video is not uploaded yet, already started, or not ready for export.
• 422 — unknown format, unknown style or a malformed URL.