---
title: "Transcribe and burn subtitles"
method: POST
path: "/tools/subtitle_video"
---

# Transcribe and burn subtitles

`POST /tools/subtitle_video`

Auto-transcribe the audio and burn styled subtitles onto the video. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until `status` is `completed` or `failed`.

## Request body

- object
  - `video_url` string, uri, required — Video URL
  - `language` '' | 'en' | 'es' | 'fr' | 'de' | 'it' | 'pt' | 'nl' | 'ru' | 'pl' | 'tr' | 'ar' | 'hi' | 'zh' | 'ja' | 'ko' | 'id' | 'vi' | 'th' — Auto detect works well when the audio is clear
  - `words_per_segment` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10, nullable — Words on screen at once
  - `font` 'inter' | 'roboto' | 'open-sans' | 'noto-sans' | 'montserrat' | 'poppins' | 'bebas-neue' | 'anton' | 'oswald' | 'playfair-display' — Defaults to Inter
  - `font_size` integer — Defaults to 28
  - `color` string — Defaults to white
  - `bold` 'off' | 'on' — Bold
  - `italic` 'off' | 'on' — Italic
  - `alignment` '2' | '1' | '3' | '5' | '4' | '6' | '8' | '7' | '9' — Defaults to Bottom Center
  - `outline_width` integer — Text outline width or box padding
  - `outline_color` string — Defaults to black
  - `shadow_size` integer — Hard drop shadow, offset down-right
  - `shadow_color` string — Defaults to black
  - `background_style` 'none' | 'box' — Solid box puts an opaque panel behind the text
  - `background_color` string — The colour of the box behind the text
  - `background_opacity` integer — 0 is fully transparent, 100 fully opaque
  - `metadata` string — Arbitrary metadata string stored with the tool run

## Response `202`

Tool run accepted

- object
  - `uid` string
  - `tool` 'subtitle_video'
  - `status` 'pending' | 'running' | 'completed' | 'failed' — pending → running → completed / failed
  - `progress` integer — 0-100 job progress, 100 once completed
  - `inputs` object — Inputs the job was created with
  - `outputs` object
    - `video_url` string, uri
  - `metadata` string, nullable — Arbitrary metadata string round-tripped from the create request
  - `self` string, uri
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `error_message` string, nullable — Human-readable failure reason (only present on failed jobs)

## Other responses

- `402` — API quota exhausted — upgrade required
- `404` — Unknown tool
- `422` — Input validation failure

---

[API](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api.md) · [All operations](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bannerbear/bannerbear-v5-api/revisions/6aa425420a10/schema)