Captions can be styled globally and edited down to the word level. This lets you highlight keywords, fix errors, and align captions to a brand style.

## Endpoints [#endpoints]

* `POST /v1/projects/{project_id}/captions`
* `GET /v1/projects/{project_id}/captions`
* `GET /v1/projects/{project_id}/captions/{caption_id}`
* `PATCH /v1/projects/{project_id}/captions/{caption_id}`
* `GET /v1/projects/{project_id}/captions/style`
* `PATCH /v1/projects/{project_id}/captions/style`
* `GET /v1/projects/{project_id}/captions/words`
* `POST /v1/projects/{project_id}/captions/words/emphasis`
* `POST /v1/projects/{project_id}/captions/words/style`
* `POST /v1/projects/{project_id}/captions/words/text`
* `POST /v1/projects/{project_id}/captions/words/retime`
* `POST /v1/projects/{project_id}/captions/words/delete`
* `POST /v1/projects/{project_id}/captions/words/merge`
* `POST /v1/projects/{project_id}/captions/words/split`
* `GET /v1/caption-looks`
* `GET /v1/caption-themes`
* `POST /v1/caption-themes`
* `PATCH /v1/caption-themes/{theme_id}`

## Apply a Caption Style [#apply-a-caption-style]

Use a Caption Look ID to apply a consistent style.

```bash title="Terminal"
curl -X PATCH https://blitzreels.com/api/v1/projects/{project_id}/captions/style \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "look_id": "editor-premium-lime" }'
```

## Get Current Caption Style [#get-current-caption-style]

```bash title="Terminal"
curl https://blitzreels.com/api/v1/projects/{project_id}/captions/style \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## List Caption Looks [#list-caption-looks]

Use this to discover the built-in looks meant for creators and agents.

```bash title="Terminal"
curl https://blitzreels.com/api/v1/caption-looks \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## List Custom Caption Themes [#list-custom-caption-themes]

Use this before copying a previous video's theme settings or setting a workspace default.

```bash title="Terminal"
curl https://blitzreels.com/api/v1/caption-themes \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## Update Caption Style [#update-caption-style]

Send only the fields you want to change (camelCase keys).

```bash title="Terminal"
curl -X PATCH https://blitzreels.com/api/v1/projects/{project_id}/captions/style \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "style": {
      "fontSize": 52,
      "fontFamily": "Anton",
      "textStrokeEnabled": true,
      "textStrokeColor": "#000000",
      "textStrokeWidthPx": 6
    }
  }'
```

## List Caption Words [#list-caption-words]

Use this before word edits to get IDs and timing.

```bash title="Terminal"
curl "https://blitzreels.com/api/v1/projects/{project_id}/captions/words?limit=100" \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

Filter by exact word text or a caption timeline item:

```bash title="Terminal"
curl "https://blitzreels.com/api/v1/projects/{project_id}/captions/words?timeline_item_id={timeline_item_id}&match_text=IA" \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## List and Patch Caption Blocks [#list-and-patch-caption-blocks]

Use caption-block endpoints when you need the whole caption text, or when an edit changes token count.

```bash title="Terminal"
curl https://blitzreels.com/api/v1/projects/{project_id}/captions \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

```bash title="Terminal"
curl -X PATCH https://blitzreels.com/api/v1/projects/{project_id}/captions/{caption_id} \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"text\": \"Pourquoi l'IA écrit du code propre\" }"
```

## Emphasize Words [#emphasize-words]

You can target words by ID, exact text, or pattern.

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/emphasis \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emphasis": true, "match_pattern": "numbers" }'
```

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/emphasis \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emphasis": false, "word_ids": ["word-uuid"] }'
```

## Update Word Styles [#update-word-styles]

Style overrides are applied per word. Use `clear_existing` to reset old overrides.

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/style \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "style": { "color": "#FFEE00", "isKeyword": true },
    "match_text": "important"
  }'
```

## Update a Word Text [#update-a-word-text]

Use this for precise corrections when you know the word ID.

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/text \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "word_id": "word-uuid", "new_text": "corrected" }'
```

## Retime Words [#retime-words]

Use this after splitting or inserting words when the displayed timing needs exact control.

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/retime \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "word_id": "word-chatgpt", "start_seconds": 35.93, "end_seconds": 36.87 }
    ]
  }'
```

## Delete, Merge, or Split Words [#delete-merge-or-split-words]

Use these when a correction changes token count, such as `de Expo` to `d'Expo`.

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/merge \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "word_ids": ["word-de", "word-expo"], "text": "d'\''Expo" }'
```

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/delete \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "word_ids": ["word-uuid"] }'
```

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/captions/words/split \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "word_id": "word-uuid", "words": ["Next", ".js"] }'
```

## Tips [#tips]

* Prefer transcript bulk corrections for repeated typos.
* Use `timeline_item_id` when editing captions for a specific clip.
* Combine emphasis with word style overrides for stronger visual impact.

## Related [#related]

* [Transcript API](/docs/transcript)
* [Timeline Editing API](/docs/timeline)