Ask AI
All Categories
Developers
Starter guide: caption a video using the API

Starter guide: caption a video using the API

Use the API to create and translate subtitles

Last updated on February 25, 2025

Use case

This guide is useful if you have a video that you want captioned and can use our API.

Before you start

Get an API key from the CaptionHub UI. In the rest of this guide we’ll assume that you have the CAPTIONHUB_API_TOKEN in your environment. You can set this with:

export CAPTIONHUB_API_TOKEN=your-token-from-the-ui

1: Create a project

Use the Create project endpoint:
curl https://api.captionhub.com/api/v1/projects \
	-X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $CAPTIONHUB_API_TOKEN" \
  -d '{"name":"My first project","original_media_url":"https://captionhub-public-test-data.s3.eu-west-1.amazonaws.com/media/brompton.mp4"}'

You’ll get back a JSON response that looks like this. Make a note of the project slug - we’ll need that to in subsequent calls.

View the full description of the response.
{
  "id": 23456789,
  "slug": "project321",
  "name": "My first project",
	...
}

Your video will now be encoded for use on CaptionHub. Depending on the size of your video this can take between a couple of minutes and several hours. Use the Get project endpoint to check up on the ready_for_processing status, or subscribe to project.encode_completed webhook.

2: Create original captions

Refer to the Create original caption set endpoint for all options.
curl https://api.captionhub.com/api/v1/caption_sets/original \
	-X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $CAPTIONHUB_API_TOKEN" \
  -d '{"project_id":"project321","language_code":"EN-GB","transcription":true}'

Your video will now be transcribed. Depending on the chosen transcription engine, this typically takes about 25% of the video’s runtime (so an hour of video is transcribed in 15 minutes). Use the Get project endpoint to check up on the original_caption_set.ready status or subscribe to the caption_set.transcribed webhook.

When the transcription is finished, you can download the subtitles:

See the Download original captions endpoint for more options.
curl 'https://api.captionhub.com/api/v1/caption_sets/original?project_id=project321&captions_format=vtt' \
  -H "Authorization: $CAPTIONHUB_API_TOKEN"

3. Create a translation

Refer to the Create translated caption set endpoint for all options.
curl https://api.captionhub.com/api/v1/caption_sets/translation \
	-X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $CAPTIONHUB_API_TOKEN" \
  -d '{"project_id":"project321","language_code":"FR","autotranslation":true}'

This will return a JSON object with an id. You can use the id to download the translated captions.

Your captions will now be translated. This is typically very fast (less than a minute). Use the Get project endpoint to check up on the ready status of the caption set, or listen to the caption_set.translated webhook.

Refer to the  Download translated caption set endpoint for all options.
curl 'https://api.captionhub.com/api/v1/caption_sets/translation?caption_set_id=2916318&captions_format=vtt' \
  -H "Authorization: $CAPTIONHUB_API_TOKEN"
 
Did this answer your question?
😞
😐
🤩
Webhooks