---
title: "add_captions: Burn captions into a clip"
description: "Transcribe a clip's speech and burn social captions into it, as a new video in the library."
canonical_url: "https://meetkuro.com/agents/tools/add_captions/"
updated: 2026-11-03
locale: "en"
tool: "add_captions"
scopes: ["generation.write"]
---

# add_captions

**Burn captions into a clip**

Transcribe a clip's speech and burn social captions into it, as a new video in the library. Costs about five credits and takes a few minutes; get_generation waits for the result.
Say nothing beyond `source` and you get the default look. `preset` is one of pop, clean, karaoke, boxed, word — "word" puts ONE WORD on screen at a time, large, which is the look short-form feeds use.
`style` is the whole caption, and it overrides whichever preset it is given with: type and weight, size as a fraction of the frame's short edge, casing, fill and highlight colours, an outline or a plate behind the words, where they sit, and `grouping`, which decides how many words share a cue.
A finished run carries its caption back on `get_generation`'s `caption_style`, so 'the same captions on this other clip' is that value handed straight back here.

## Scope

- `generation.write` — Makes, edits, imports, shares and deletes media in the account.

## Behaviour

- **Writes**: Creates or changes items in the caller's own account.
- **Adds or updates**: Adds or updates; nothing the caller already has is deleted or overwritten.
- **Stays in the account**: Stays inside the caller's private Kuro account: any media provider it calls acts on Kuro's account, and the result is visible to no one else.

## Credits

What the tool's description says about credits, verbatim:

- Costs about five credits and takes a few minutes; get_generation waits for the result.

## Inputs

| Name | Type | Required | Details |
| --- | --- | --- | --- |
| `source` | object (type: "upload") or object (type: "generation") | yes | — |
| `preset` | string | no | one of "pop", "clean", "karaoke", "boxed", "word" |
| `style` | object (schema_version: "1.0") | no | fields: schema_version, font_id, font_weight, italic, font_scale, casing, color, highlight, highlight_color, border, anchor, margin_v, margin_h, grouping |

## Example call

A `tools/call` request with the required arguments only, each a placeholder read off the schema. Replace them before sending.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_captions",
    "arguments": {
      "source": {
        "type": "upload",
        "upload_id": "00000000-0000-4000-8000-000000000000"
      }
    }
  }
}
```

## Input schema

As the server sends it in `tools/list`:

```json
{
  "type": "object",
  "properties": {
    "source": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "upload"
            },
            "upload_id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "type",
            "upload_id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "generation"
            },
            "generation_id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "type",
            "generation_id"
          ],
          "additionalProperties": false
        }
      ]
    },
    "preset": {
      "type": "string",
      "enum": [
        "pop",
        "clean",
        "karaoke",
        "boxed",
        "word"
      ]
    },
    "style": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "const": "1.0",
          "default": "1.0"
        },
        "font_id": {
          "type": "string",
          "enum": [
            "inter",
            "montserrat",
            "oswald",
            "archivo-black",
            "noto-sans",
            "tiktok-sans"
          ],
          "default": "noto-sans"
        },
        "font_weight": {
          "type": "integer",
          "minimum": 100,
          "maximum": 900,
          "multipleOf": 100,
          "default": 700
        },
        "italic": {
          "type": "boolean",
          "default": false
        },
        "font_scale": {
          "type": "number",
          "minimum": 0.02,
          "maximum": 0.2,
          "default": 0.075
        },
        "casing": {
          "type": "string",
          "enum": [
            "none",
            "upper"
          ],
          "default": "upper"
        },
        "color": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$",
          "default": "#FFFFFF"
        },
        "highlight": {
          "type": "string",
          "enum": [
            "none",
            "active_word",
            "karaoke"
          ],
          "default": "active_word"
        },
        "highlight_color": {
          "$ref": "#/properties/style/properties/color",
          "default": "#FFD700"
        },
        "border": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "outline"
                },
                "color": {
                  "$ref": "#/properties/style/properties/color",
                  "default": "#000000"
                },
                "scale": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 0.3,
                  "default": 0.049
                },
                "shadow_scale": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 0.3,
                  "default": 0.012
                }
              },
              "required": [
                "kind"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "plate"
                },
                "color": {
                  "$ref": "#/properties/style/properties/color",
                  "default": "#000000"
                },
                "pad_scale": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 0.3,
                  "default": 0.025
                }
              },
              "required": [
                "kind"
              ],
              "additionalProperties": false
            }
          ],
          "default": {
            "kind": "outline",
            "color": "#000000",
            "scale": 0.049,
            "shadow_scale": 0.012
          }
        },
        "anchor": {
          "type": "string",
          "enum": [
            "top",
            "bottom"
          ],
          "default": "bottom"
        },
        "margin_v": {
          "anyOf": [
            {
              "type": "string",
              "const": "auto"
            },
            {
              "type": "number",
              "minimum": 0,
              "maximum": 0.45
            }
          ],
          "default": "auto"
        },
        "margin_h": {
          "type": "number",
          "minimum": 0,
          "maximum": 0.4,
          "default": 0.06
        },
        "grouping": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "word",
                "phrase",
                "sentence"
              ],
              "default": "phrase"
            },
            "max_words": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 24
                },
                {
                  "type": "null"
                }
              ],
              "default": null
            },
            "max_chars": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 8,
                  "maximum": 160
                },
                {
                  "type": "null"
                }
              ],
              "default": null
            },
            "gap_seconds": {
              "anyOf": [
                {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 4
                },
                {
                  "type": "null"
                }
              ],
              "default": null
            },
            "max_lines": {
              "type": "number",
              "enum": [
                1,
                2
              ],
              "default": 2
            }
          },
          "additionalProperties": false,
          "default": {
            "unit": "phrase",
            "max_words": null,
            "max_chars": null,
            "gap_seconds": null,
            "max_lines": 2
          }
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "source"
  ],
  "additionalProperties": false
}
```

## Related tools

- [`get_generation`](https://meetkuro.com/agents/tools/get_generation.md): Get current status and signed media URL for one generation.

---

## About Kuro

Kuro is an AI picture studio: prompt-driven images, clips, voice-overs and music, and storyboard-backed films with consistent characters across every scene.

Agents connect over MCP and can generate directly:

```
claude mcp add kuro https://api.meetkuro.com/mcp --transport http
```

The app is at https://app.meetkuro.com and requires an account.

Each guide, model page, comparison and free tool page on this site (not a tool's variants, and not the index pages) has a Markdown twin at its own URL plus `.md`, and so do /benchmarks/, the English /agents/ page (as /agents.md) and the MCP tool reference. Every tool: https://meetkuro.com/agents/tools/