2026-09-26미디어 도구

자막 커스터마이즈 API: 색, 위치, 크기, 줄당 단어 수

Sume의 design 객체로 영상에 입히는 자막을 커스터마이즈하세요. punch와 tiktok-green을 뺀 모든 스타일에서 색, 위치, 크기, 구절당 단어 수를 덮어씁니다.

읽는 시간 5분Sume

Sume API로 영상에 입히는 자막을 커스터마이즈하려면 POST /v1/video-captions에 design 객체를 추가하세요. 키 하나가 선택한 스타일의 토큰 하나를 덮어씁니다. colors.active는 발화 중인 단어의 색을 바꾸고, placement.anchor_ratio는 자막 줄을 위아래로 옮기며, typography.font_size_ratio는 크기를 정하고, phrasing.max_words는 구절당 단어 수의 상한을 정합니다.

토큰 이름과 범위는 2026-09-26에 확인한 Sume의 영상 캡션 페이지와 API 레퍼런스 스키마에서 가져왔고, 스타일별 시작값은 렌더러의 현재 기본값입니다. 애초에 스타일을 고르는 방법은 영상에 자막을 입히는 방법에서 다룹니다.

디자인 오버라이드는 어떻게 동작하나요?

스타일은 디자인 토큰의 묶음이고, design은 그 토큰을 요청 하나에 대해 덮어씁니다. 모든 필드는 선택 사항이며 스타일의 값 위에 병합되므로, 키 하나는 한 가지만 바꾸고 나머지는 스타일이 그리는 그대로 남습니다. design은 punch와 tiktok-green을 뺀 모든 스타일에서 동작합니다. 이 두 스타일은 이 토큰을 하나도 읽지 않는 경로로 렌더링됩니다.

다음 요청은 black-outline을 유지하되, 발화 중인 단어의 색을 바꾸고, 자막 줄을 내리고, 구절마다 길이를 줄입니다.

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-design-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "black-outline",
    "design": {
      "colors": { "active": "#22D3EE" },
      "placement": { "anchor_ratio": 0.8 },
      "phrasing": { "max_words": 4 }
    }
  }'

어떤 토큰을 바꿀 수 있고, 범위는 어떻게 되나요?

색은 hex, rgb() / rgba(), transparent를 받습니다. 숫자는 다음 범위 안에 있어야 합니다.

영상 캡션과 API 레퍼런스 스키마 기준, 2026-09-26 확인.
토큰	범위	정하는 것
`colors.base`, `colors.active`	색	기본 상태 텍스트와 발화 중인 단어.
`colors.stroke`	색	스타일이 외곽선을 그리는 경우의 외곽선 색.
`colors.accent`, `colors.accent_deep`	색	하이라이트 블록이나 스윕, 그리고 그 그라데이션의 반대쪽 끝(기본값은 `accent`).
`colors.card`	색 또는 `null`	카드나 알약 모양 배경의 채움 색. `null`이면 카드를 그리지 않음.
`typography.base_weight`, `active_weight`	100–1000	기본 상태 텍스트와 발화 중인 단어의 가변 폰트 굵기.
`typography.active_scale`	0.5–2	발화 중인 단어에 적용하는 배율.
`typography.font_size_ratio`	0.01–0.4	너비 1080 프레임 대비 글자 크기 비율(맞춤 과정에서 긴 줄을 줄이기 전 값).
`typography.safe_width_ratio`	0.3–1	자막 줄 하나가 차지할 수 있는 프레임 너비 비율.
`typography.stroke_width_px`	0–24	너비 1080 기준의 외곽선 두께(픽셀).
`placement.anchor_ratio`, `landscape_anchor_ratio`	0.05–0.95	세로 화면과 가로 화면에서 프레임 높이 대비 자막 줄 중심의 위치 비율.
`phrasing.max_words`	1–12	화면에 뜨는 구절 하나의 단어 수.
`phrasing.max_chars`	4–60	화면에 뜨는 구절 하나의 글자 수.
`phrasing.pause_seconds`	0.05–3	한 구절을 끊고 다음 구절로 넘어가게 하는 무음 길이.
`motion.enter_seconds`, `exit_seconds`, `emphasis_in_seconds`, `emphasis_out_seconds`	0–2	구절이 들어오고 나가는 시간, 그리고 발화 중인 단어가 강조를 받고 놓는 데 걸리는 시간.

자막을 위아래로 옮기려면 어떻게 하나요?

placement.anchor_ratio를 설정하세요. 렌더러는 현재 프레임 위에서부터 그 비율만큼 내려온 지점에 자막 줄의 중심을 놓습니다. 그래서 0.05는 맨 위 근처, 0.95는 맨 아래 근처입니다. anchor_ratio만 보내면 가로 화면 위치도 그 값을 따릅니다. 가로 프레임의 위치를 따로 정하려면 landscape_anchor_ratio도 함께 보내세요.

크기와 줄당 단어 수는 어떻게 바꾸나요?

typography.font_size_ratio는 너비 1080 프레임을 기준으로 글자 크기를 정하고, safe_width_ratio는 줄 하나가 너비를 얼마나 차지할 수 있는지 정합니다. 그래도 긴 줄은 더 작게 렌더링될 수 있습니다. 브라우저 안에서 이뤄지는 맞춤 과정이 줄을 안전 너비에 맞게 줄이기 때문입니다.

phrasing.max_words와 phrasing.max_chars는 화면에 뜨는 구절 하나의 상한을 정하고, pause_seconds보다 긴 무음이 오면 새 구절이 시작됩니다. slam은 한 번에 한 단어씩 보여 주므로, 현재 이 스타일에서는 구절 상한이 아무 효과가 없습니다.

각 스타일은 어떤 값에서 시작하나요?

오버라이드는 스타일의 현재 기본값을 고치는 것이므로, 작은 변경은 그 스타일 본래의 룩에서 크게 벗어나지 않습니다. design을 받는 스타일 가운데 다섯 개는 현재 다음 값에서 시작합니다.

Sume 자막 렌더러의 현재 기본값, 2026-09-26 확인. 토큰 이름은 영상 캡션 기준.
스타일	앵커(세로)	구절당 단어 / 글자 수	발화 단어 색
`slam`	0.58	한 번에 한 단어	`#FFD700`
`black-outline`	0.64	7 / 22	`#FFD700`
`highlight`	0.7	7 / 22	`#ff1745`에서 `#c40f31`로 이어지는 그라데이션 블록 위의 흰색
`pill-karaoke`	0.74	7 / 22	`rgba(12,12,16,0.82)` 알약 모양 배경 안의 `#FFD700`
`korean-ad`	0.76	5 / 14	`#FFE14D`

design이 하지 않는 일은 무엇인가요?

design은 룩을 고칠 뿐 서체나 문구를 고르지 않으며, 안전하게 그릴 수 없는 값은 거부합니다.

punch와 tiktok-green에서는 지원하지 않습니다.
그 밖의 CSS 문법으로 쓴 색은 렌더 문서에 그려지지 않고 거부됩니다.
범위를 벗어난 숫자는 400이므로, 잘못된 룩은 잘못 렌더링되고 과금되는 대신 요청 시점에 실패합니다.
서체는 한글 스타일 전용의 별도 필드인 font가 정합니다. 문구는 음성 인식, script_text, words, cues 중 하나에서 옵니다.
style을 생략하면 발화 중인 단어가 글자색 그대로 렌더링됩니다. 금색 강조를 유지하려면 black-outline이나 slam을 직접 지정하거나, design.colors.active를 설정하세요.
design은 POST /v1/video-captions의 필드입니다. 아바타 영상의 captions 객체에는 design 필드가 없습니다.

출처

작성자 Sume