한국어 자막 API: 두부 글자 없는 한글 자막 스타일과 폰트

Sume API로 한국어 자막을 입히려면 black-outline이나 korean-ad처럼 한글을 지원하는 style을 지정해 POST /v1/video-captions를 보내고, 선택 사항인 음성 인식 힌트로 language: "ko"를 함께 넣으세요. 라틴 스타일인 slam, punch, tiktok-green에는 한글 글립이 없으므로, Sume는 이 스타일로 보낸 한국어 문구를 두부 글자(tofu)로 새기지 않고 거부합니다.

아래 규칙은 2026-09-26에 확인한 Sume의 영상 캡션 문서와 아바타 영상 생성 문서를 기준으로 하며, 현재 API 동작에서 가져온 내용은 따로 밝혀 두었습니다. 일반적인 자막 작업 흐름은 영상에 자막을 입히는 방법에서 다룹니다.

한국어 자막은 어떻게 요청하나요?

필수 필드는 video_url 하나뿐이며, 가져올 수 있는 공개 HTTPS 영상 URL이어야 합니다. 다음 요청은 한국어 음성에 광고형 카라오케 룩을 요청합니다.

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"
  }'

한국어 자막은 왜 두부 글자로 나오나요?

두부 글자는 폰트에 해당 문자의 글립이 없을 때 렌더러가 대신 그리는 빈 네모입니다. slam, punch, tiktok-green은 한글 글립이 없는 라틴 디스플레이 서체로 그리므로, Sume는 Job의 스타일을 바꾸는 대신 이 조합을 거부합니다.

• slam, punch, tiktok-green에 한국어 문구를 보내면 caption_hangul_text_latin_style과 함께 400을 반환합니다.
• 라틴 스타일과 함께 한글 font를 지정하면 caption_font_requires_hangul_style과 함께 400을 반환합니다.
• Sume는 현재 문구의 글자 가운데 절반 이상이 한글이면 그 문구를 한국어로 판단합니다. 영어가 대부분인 혼합 문구라면 기본값에 기대지 말고 한글 스타일을 직접 지정하세요.
• 요청에 문구가 없으면 음성 인식 결과가 나온 뒤 그 전사문에 같은 검사를 적용하며, 조합이 맞지 않으면 Job이 실패합니다.

어떤 한글 자막 스타일을 써야 하나요?

한글을 지원하는 스타일은 한국어 음성용 한글 아이덴티티와 korean-ad입니다. 아이덴티티는 단어를 하나씩 띄우지 않고 어절을 구절 카드로 묶으며, 대소문자 변환 없이 전사문을 쓰인 그대로 새깁니다. korean-ad는 광고형 카라오케 룩으로, weight-shift에 발화 어절 강조색을 더한 스타일입니다.

스타일을 생략하면 어떻게 되나요?

문구가 스타일을 정합니다. 한국어 문구는 black-outline으로, 라틴 문구는 slam으로 정해집니다. korean-ad로 정해지는 일은 없으므로 이 스타일은 이름으로 직접 지정하세요. 직접 지정한 스타일은 지정한 그대로 렌더링됩니다.

• style을 생략하면 기본 스타일에 원래 설정된 발화 어절의 금색 강조도 빠지므로, 발화 어절도 글자색을 그대로 유지합니다. black-outline을 직접 지정하면 그 금색 강조가 남고, 어느 쪽이든 design.colors.active로 그 색을 정할 수 있습니다.
• language는 음성 인식에 어떤 언어(ko, en, …)를 기대할지 알려 줄 뿐 스타일이나 폰트를 고르지 않습니다. 따라서 language: "ko"만으로는 라틴 스타일을 한국어에 안전하게 쓸 수 없습니다.

어떤 한글 폰트를 쓸 수 있나요?

font는 선택 사항이며 한글 스타일에서만 받습니다. 생략하면 스타일의 기본 서체를 쓰고, 지정하면 스타일은 그대로 두고 서체만 바꿉니다. 모든 서체는 SIL Open Font License 1.1이며 렌더러에 함께 들어 있고, 목록에 없는 이름은 다른 서체로 바꿔치기하지 않고 거부합니다.

weight-shift와 korean-ad는 wght 축을 애니메이션하는데, 이 축은 Pretendard에만 있습니다. 고정 굵기 서체에서는 두 스타일 모두 색과 크기 강조는 유지되지만 굵기 변화는 사라집니다. editorial-emphasis는 강조 줄을 항상 검은고딕으로 그리며, font는 앞 줄을 바꿉니다. 문서의 느낌 분류로 묶은 font 값은 다음과 같습니다.

• 범용 산세리프: noto-sans-kr, ibm-plex-sans-kr, gothic-a1, nanum-gothic. 범용 세리프: noto-serif-kr, nanum-myeongjo.
• 디스플레이: hahmlet, song-myung, stylish, sunflower. 손글씨 / 스크립트: poor-story, gamja-flower, gaegu, cute-font, east-sea-dokdo.
• 임팩트: black-han-sans. 초굵은 임팩트: gasoek-one. 두툼한 라운드: do-hyeon, bagel-fat-one.
• 부드럽고 귀여운 라운드: jua, hi-melody. 장난기 있는 라운드 디스플레이: dongle. 부드러운 에디토리얼: gowun-dodum.
• 깔끔한 기본: pretendard. 기하학적 리테일 디스플레이: gmarket-sans. 붓글씨 느낌: yeon-sung. 손글씨: nanum-pen. 부드러운 손글씨: single-day. 픽셀 / 레트로: dunggeunmo.

아바타 영상에도 한국어 자막을 넣을 수 있나요?

네, 두 가지 방법이 있습니다. 말하는 영상이 완성되면 다른 완성 클립과 마찬가지로 그 media.sume.com 영상 URL을 한글 스타일과 함께 POST /v1/video-captions로 보내고, 아바타 스크립트를 script_text로 넘겨 작성한 문구를 그대로 새기세요. 이 독립 실행형 Job은 현재 고정 추정 기준으로 60초 이하 영상에 대해 영상 캡션 페이지에 나온 고정 금액으로 과금됩니다.

또는 아바타 영상 프리뷰를 만들 때 인라인 captions를 저장해 두면 generate-video 단계에서 적용됩니다. 인라인 자막은 style, 선택 font, language 힌트, script_text를 받으며 기본 스타일은 slam입니다. 한국어 스크립트에 slam, punch, tiktok-green을 쓰면 400 caption_hangul_text_latin_style로 거부되고, 추정 길이가 60초를 넘어도 거부됩니다. 한국어에도 안전한 captions 객체는 다음과 같습니다.

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