Korean subtitles API: Hangul caption styles and fonts without tofu

To burn Korean subtitles with the Sume API, send POST /v1/video-captions with a Hangul-safe style such as black-outline or korean-ad, plus language: "ko" as an optional speech-to-text hint. The Latin styles slam, punch, and tiktok-green have no Hangul glyphs, so Sume rejects Korean copy on them instead of burning tofu boxes.

The rules below come from Sume's Video captions and Generate avatar video docs, read on 2026-09-26, plus current API behavior where noted. The general caption workflow is in How to burn captions onto a video.

How do I request Korean captions?

video_url is the only required field, and it must be a fetchable public HTTPS video URL. This request asks for the ad karaoke look on Korean speech:

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-caption-ko-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "korean-ad",
    "language": "ko"
  }'

Why do Korean captions turn into tofu?

Tofu is the empty box a renderer draws when a font has no glyph for a character. slam, punch, and tiktok-green draw in Latin display faces with no Hangul glyphs, so Sume refuses the pairing rather than re-styling your job:

• Korean copy on slam, punch, or tiktok-green returns 400 with caption_hangul_text_latin_style.
• A Hangul font named alongside a Latin style returns 400 with caption_font_requires_hangul_style.
• Sume currently treats wording as Korean when at least half of its letters are Hangul. For mixed copy that is mostly English, name a Hangul style rather than relying on the default.
• With no wording in the request, the same check runs on the transcript once speech-to-text returns, and a mismatch fails the job.

Which Hangul caption style should I use?

The Hangul-safe styles are the identities for Korean speech plus korean-ad. The identities group words into phrase cards instead of one word at a time, and burn the transcript exactly as written, with no case folding. korean-ad is the ad karaoke look: weight-shift with an accent color on the spoken word.

What happens if I leave out the style?

The wording decides: Korean copy resolves to black-outline and Latin copy to slam. It never resolves to korean-ad, so ask for that one by name. A style you name is rendered as named.

• An omitted style also drops the gold spoken-word tint the default styles were authored with, so the spoken word keeps the fill color. Naming black-outline keeps its gold tint, and design.colors.active sets the color either way.
• language only tells speech-to-text what to expect (ko, en, …) and never selects the style or the font, so language: "ko" alone does not make a Latin style safe for Korean.

Which Korean fonts can I use?

font is optional and accepted on Hangul styles only. Omit it to keep the style's own face; set it to keep the style and swap the face. Every face is SIL Open Font License 1.1 and ships with the renderer, and a name outside the list is rejected rather than substituted.

weight-shift and korean-ad animate the wght axis, which only Pretendard carries. On a static face those two keep their color and scale emphasis but lose the weight travel. editorial-emphasis always draws its emphasis line in Black Han Sans; font moves its lead line. The font values, grouped by the docs' feel labels:

• Workhorse sans: noto-sans-kr, ibm-plex-sans-kr, gothic-a1, nanum-gothic. Workhorse serif: noto-serif-kr, nanum-myeongjo.
• Display: hahmlet, song-myung, stylish, sunflower. Script: poor-story, gamja-flower, gaegu, cute-font, east-sea-dokdo.
• Impact: black-han-sans. Ultra-thick impact: gasoek-one. Thick rounded: do-hyeon. Fat rounded: bagel-fat-one.
• Soft cute rounded: jua. Soft rounded cute: hi-melody. Playful rounded display: dongle. Soft editorial: gowun-dodum.
• Clean baseline: pretendard. Geometric retail display: gmarket-sans. Brushy: yeon-sung. Handwritten: nanum-pen. Soft cute handwritten: single-day. Pixel / retro: dunggeunmo.

Can I put Korean captions on an avatar video?

Yes, in two ways. Once the talking video is done, send its media.sume.com video URL to POST /v1/video-captions with a Hangul style, like any finished clip, and pass the avatar script as script_text to burn your exact wording. That standalone job bills the fixed amount listed on the Video captions page, for videos up to 60 seconds under the current fixed estimate.

Or store inline captions when you create an avatar video preview; they apply at generate-video. Inline captions take style, optional font, a language hint, and script_text, and default to slam. A Korean script with slam, punch, or tiktok-green is rejected with 400 caption_hangul_text_latin_style, and an estimated duration above 60 seconds is rejected too. A Korean-safe captions object:

{
  "captions": {
    "enabled": true,
    "style": "black-outline",
    "language": "ko"
  }
}