# Importing captions over the API

**Category:** [Video Hub](https://help.totalctrl.app/hc/totalctrl/totalctrl-help-center/en-US/categories/subtitles)
**Updated:** 2026-08-19

## Create a track from a caption file

Creating a track accepts captions directly, so an integration does not have to create an empty track and then fill it.

`POST /api/v1/videohub/projects/<project_uid>/tracks`
### Three ways to fill a new track

- **Empty** — send just a `language`. You edit the cues yourself.
- **Transcribe** — send `transcribe: true`. This spends AI Units and counts against your monthly transcription limit.
- **Import** — send either `content` (the WebVTT or SRT text) or `caption_asset_uid` (a `.vtt` or `.srt` already in Digital Assets).

### Fields

- `language` — language code, for example `es-ES`. Defaults to `en`.
- `label` — an optional display name for the track.
- `transcribe` — boolean.
- `content` — WebVTT or SRT text.
- `caption_asset_uid` — the uid of a caption file in Digital Assets. Find one with `GET /api/v1/assets`.

### What is refused

Asking to import *and* transcribe returns `400`: both would derive cues, and one of them would be thrown away after being paid for. An asset that is not a caption file also returns `400`, and no track is created — an empty track left behind by a rejected file is worse than an error, because nothing about it says it is empty on purpose.
### What you get back

A `201` with the track. An imported track comes back with status `ready` and source `imported`, and `videohub.track.imported` fires so a workflow can pick it up.

---

## Related Articles

- [The caption editor](https://help.totalctrl.app/en-US/articles/subtitles-editor-1)
- [What is Video Hub?](https://help.totalctrl.app/en-US/articles/subtitles-overview-1)
- [The caption editor](https://help.totalctrl.app/en-US/articles/subtitles-editor-2)
- [The caption editor](https://help.totalctrl.app/en-US/articles/subtitles-editor)
- [Create a project and transcribe](https://help.totalctrl.app/en-US/articles/subtitles-create-transcribe-1)

---
[← Back to TotalCtrl Help Center](https://help.totalctrl.app/en-US/)