Korean captions API error: caption_hangul_text_latin_style (400)

If POST /v1/video-captions returns 400 caption_hangul_text_latin_style, you sent Korean text to a Latin caption style. slam, punch, and tiktok-green use display faces with no Hangul glyphs, so they would burn tofu boxes. Sume refuses the request instead of switching styles. Pick a Hangul style such as black-outline, korean-ad, or clip-wipe and resend.

Why the API refuses instead of falling back

The docs give the reason in one line: a caption style you did not select is worse than an error. The alternative is a video full of tofu boxes at the same price as a good video. The rule also covers font: a Hangul face sent with a Latin style returns caption_font_requires_hangul_style. Latin text on slam works as before.

Which styles to use for Korean speech

If you do not send style, the language of the caption text decides: Korean resolves to black-outline, Latin to slam. If you want the ad look, you must ask for it, since korean-ad is not the default. Karaoke-style accents are also not added to a default render.

A working request

language is only a speech-to-text hint (ko, en) and never selects the style or the font. The video must be a public HTTPS URL that Sume can fetch.

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

Choosing between Hangul styles

For talking-head and creator speech, black-outline is the safe default and needs no other fields. For ad creative, korean-ad gives the karaoke look with an accent on the spoken word. For small phone screens, the docs call clip-wipe the clearest. For a magazine look, editorial-emphasis puts the last word of each phrase on a second line at about twice the size in Black Han Sans.

Combine styles with design overrides to change a single token, for example the accent color, without changing anything else: design.colors.active. Numbers outside a documented range return a 400 at request time, so a bad look fails before you pay. Note that punch and tiktok-green do not support design.

Cost and fonts

Each accepted standalone caption job reserves and captures $0.20 for videos up to 60 seconds. A style or font error is a 400 at request time, so no job is accepted. Fonts are a fixed list (Pretendard, Do Hyeon, Black Han Sans, Jua, and others under the SIL Open Font License); any other name is rejected with no substitute. Note that weight-shift and korean-ad animate the weight axis, which only Pretendard has, so another face keeps the color and scale emphasis but loses the weight change.