HeyGen 비디오 번역
기존 비디오를 175개 이상의 언어로 번역하고 더빙합니다. 시스템이 대상 언어로 발표자의 목소리를 복제하고, 새로운 오디오에 맞춰 입 모양을 다시 동기화한 후, 완전히 더빙된 비디오를 반환합니다. 소스 비디오와 대상 언어를 제공하면 엔진이 자막 생성, 번역, 음성 복제, 립싱크 및 (선택적으로) 내장 자막을 처리합니다.
이는 새로운 비디오 생성이 아닙니다. 원본 비디오의 발표자, 연기, 프레이밍 및 브랜드 자산은 유지됩니다. 번역은 기존 콘텐츠 위에 적용됩니다.
사용자 대상 동작
- 간결하게 유지하세요. 번역 ID, 원시 API 페이로드 또는 상태 JSON을 채팅에 덤프하지 마세요. 결과(비디오 링크, 언어)를 보고하고 내부 과정은 보고하지 마세요.
- 내부 전문 용어를 사용하지 마세요. "폴링", "video_translation_id", "asset_id", "v3 엔드포인트"라고 말하지 마세요. "번역 중", "거의 완료", "파일 준비 완료"라고 말하세요.
- 폴링은 조용히 수행하세요. 장기 실행 번역을 백그라운드에서 처리하고 (a) 결과가 전달된 경우, (b) 5분 이상 지연된 경우(한 번 업데이트), (c) 심각한 오류가 발생한 경우에만 알리세요.
- 하나의 결과, 하나의 메시지. 비디오가 완료되면 링크와 한 줄 요약(대상 언어, 길이, 모드)을 보내세요. 모든 API 필드를 보내지 마세요.
- 전송 수단 선택을 언급하지 마세요. MCP, CLI 또는 OpenClaw 플러그인은 내부 사항입니다. 세션 시작 시 자동으로 선택하고, 사용 중인 방식을 언급하지 마세요.
- 사용자 언어로 소통하세요. 사용자의 첫 메시지에서 언어를 감지하세요. 답변, 확인 및 질문은 그들의 언어로 하세요. 기술적인 CLI/API 지침은 영어로 유지하세요.
API 모드 감지
세션 시작 시 하나의 전송 방식을 선택하세요. 절대 혼합하지 말고, 세션 중간에 전환하지 말고, 선택을 언급하지 마세요.
다음 순서로 감지하세요:
- OpenClaw 플러그인 모드 — OpenClaw 내에서 실행 중이고
video_generate도구가 HeyGen 번역 모델을 노출하는 경우 선호하세요. 현재 플러그인은 비디오를 생성하지만 번역을 직접 노출하지는 않습니다 — HeyGen이video_generate를 통해 번역을 제공할 때까지 다음 단계로 넘어가세요. - CLI 모드(API 키 재정의) —
HEYGEN_API_KEY가 환경에 설정되어 있고heygen --version이 0으로 종료되면 CLI를 사용하세요. API 키의 존재는 사용자가 직접 API 액세스를 원한다는 명시적 신호입니다. - MCP 모드 —
HEYGEN_API_KEY가 없고 HeyGen MCP 도구가 표시되는 경우(mcp__heygen__*). OAuth 인증, 사용자 계정 크레딧으로 실행됩니다. - CLI 모드(폴백) — MCP 도구를 사용할 수 없고
heygen --version이 0으로 종료되는 경우.heygen auth login을 통한 인증. - 둘 다 아님 — 사용자에게 한 번 알리세요: "이 스킬을 사용하려면 HeyGen MCP 서버를 연결하거나 HeyGen CLI를 설치하세요:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash그런 다음heygen auth login을 실행하세요."
인증 확인(모든 API 호출 전에 실행)
모드 감지 후, 실제로 인증이 작동하는지 확인한 후 1단계로 진입하세요. 이렇게 하면 입력을 수집하는 데 시간을 낭비하고 제출 시 인증 오류가 발생하는 것을 방지할 수 있습니다.
- MCP 모드: 인증은 OAuth로 처리됩니다 — 확인 불필요.
- CLI 모드:
heygen auth status(조용히)를 실행하세요. 0으로 종료되면 진행하세요. 0이 아닌 값으로 종료되면(키 없음, 만료, 유효하지 않음):- 사용자에게 묻습니다: "진행하려면 HeyGen API 키가 필요합니다. https://app.heygen.com/settings?nav=API에서 키를 가져올 수 있습니다 — 여기에 붙여넣어 주세요."
- 사용자가 제공하면
echo "<key>" | heygen auth login으로 영구 저장합니다(~/.heygen/credentials에 기록, 세션 간 유지). - 확인:
heygen auth status를 다시 실행합니다. 여전히 실패하면 오류를 표시하고 중지합니다.
이것은 일회성 설정입니다. heygen auth login이 키를 영구 저장하면 이후 세션에서 자동으로 인식합니다. heygen auth status가 통과하면 다시 묻지 마세요.
엄격한 규칙:
- 절대
curl api.heygen.com/...를 호출하지 마세요. 이 스킬의 모든 작업에는 CLI 명령과 (지원되는 경우) MCP 도구가 있습니다. 그것들을 사용하세요. - MCP 모드:
mcp__heygen__*도구만 사용하세요. 번역이 아직 MCP를 통해 노출되지 않은 경우, 특히 번역 작업에 대해 CLI로 폴백하세요. 원시 HTTP 호출을 합성하지 마세요. - CLI 모드:
heygen ...명령만 사용하세요.heygen video-translate --help및heygen video-translate <하위명령> --help를 실행하여 인수를 확인하세요.--request-schema를 사용하여 모든 create 명령의 전체 JSON 형식을 확인하세요. - 아래 작업은 MCP와 CLI를 나란히 보여줍니다 — 감지된 모드의 열만 읽으세요.
MCP 도구 이름(MCP 모드 전용)
create_video_translation(단일 언어). 다중 언어 및 교정은 아직 MCP를 통해 노출되지 않았습니다 — 해당 작업은 CLI로 폴백하세요. 세션 시작 시 mcp__heygen__* 도구 목록을 실행하여 사용 가능한 도구를 확인하세요. 도구 표면은 진화합니다.
CLI 명령 그룹(CLI 모드 전용)
heygen video-translate
├── languages list # 지원되는 대상 언어 나열
├── create # 번역 작업 제출(단일 또는 배치)
├── get <id> # 상태 확인 / 결과 가져오기
├── list # 과거 번역 목록 보기
├── update # 작업 메타데이터 업데이트
├── delete # 작업 삭제
└── proofreads
├── create # 최종 렌더링 전에 편집 가능한 자막 추출
├── get <id> # 교정 세션 상태 확인
├── srt get <id> # 추출된 SRT 다운로드
├── srt update <id> # 편집된 SRT 업로드
└── generate <id> # 승인된 SRT로 최종 비디오 렌더링
heygen asset create --file <경로> # 로컬 소스 비디오 업로드용(최대 32MB)
모든 명령은 --help를 지원합니다. create 명령에서 --request-schema를 사용하여 전체 JSON 본문을 확인하세요. CLI 출력: stdout에 JSON, stderr에 {error:{code,message,hint}} 봉투, 종료 코드 0 성공 · 1 API · 2 사용법 · 3 인증 · 4 시간 초과. create에 --wait를 추가하면 작업이 완료될 때까지 차단됩니다(기본 시간 초과 20분).
📖 자세한 CLI/MCP 오류 → 작업 매핑 → references/troubleshooting.md
기본 워크플로우
스킬은 네 단계로 실행됩니다. 1단계(발견)만 질문을 합니다. 2단계(사전 점검)는 조용히 진행됩니다. 3단계(제출 + 폴링)는 조용히 진행됩니다. 4단계(전달)는 짧은 메시지 하나입니다.
Phase 1 — Discovery(발견) — 사용자로부터 필요한 최소 입력 수집
Phase 2 — Pre-flight(사전 점검) — 언어 유효성 검사, 콘텐츠 분류, 플래그 설정
Phase 3 — Submit + Poll(제출+폴링) — 시작, 백그라운드 폴링, 완료/실패 시에만 알림
Phase 4 — Deliver(전달) — 한 줄 요약과 함께 결과 게시
1단계 — 발견
이미 가지고 있지 않은 것만 물어보세요. 사용자 언어로 소통하세요. 절대 양식을 실행하지 마세요. 한 번에 하나 또는 두 개의 질문, 최대로.
필수 입력(이것들을 얻을 때까지 차단):
- 소스 비디오. 공개 URL, 로컬 파일 경로 또는 이전 단계의 HeyGen asset_id. 사용자가 제공하지 않은 경우 물어보세요: "소스 비디오는 무엇인가요? URL, 파일 경로 또는 기존 HeyGen 자산입니까?"
- 대상 언어. 사용자 언어로 개방형 질문을 하세요: "어떤 언어로 번역할까요?" 선택기를 제시하거나 미리 할당된 선택지를 제공하지 마세요 — 사용자가 자유롭게 입력할 수 있도록 하세요. 하나의 언어, 여러 언어 또는 지역별 변형을 원할 수 있습니다. 제공된 내용을 그대로 받아들이고 2단계에서 정식 언어 목록에 대해 유효성을 검사하세요.
중요한 입력(제공되지 않은 경우 스마트 기본값으로 질문):
- 화자 수. 단일 화자가 기본값이며 대부분의 사용자에게 해당합니다. 모호한 경우 한 번 질문하세요: "비디오에 몇 명의 서로 다른 화자가 있습니까?" 잘못된 화자 수는 품질을 떨어뜨리는 가장 큰 원인입니다 — 화자 혼동은 번역 중간에 음성 교체를 만듭니다. 여러 사람이 있는 콘텐츠의 경우 이 질문을 건너뛰지 마세요.
- 콘텐츠 유형. 일반적으로 질문할 필요가 없습니다 — 비디오에서 유추하고 확인하세요. 아래 다섯 가지 프로필이 약 95%의 사례를 다룹니다. 진정으로 모호한 경우에만 질문하세요.
- 자막 선호도. 기본값: 토킹헤드 및 기업 콘텐츠는 ON, 팟캐스트/오디오 전용은 OFF. 기본값을 변경하는 경우 4단계에서 간략히 언급하세요.
- 길이 유연성. 질문: "번역된 비디오가 원본과 정확히 같은 길이여야 합니까, 아니면 약간 더 길거나 짧아도 괜찮습니까? 유연성을 허용하면 일반적으로 더 자연스럽게 들립니다 — 번역된 음성이 압축되거나 속도가 조정되는 대신 편안한 속도로 말할 충분한 공간을 얻습니다." 기본 권장: 유연함(
enable_dynamic_duration: true). 사용자가 정확한 시간(예: 타임라인, 광고 슬롯 또는 외부 오디오 트랙에 동기화)이 필요한 경우에만false로 설정하세요. 음조 압축으로 인해 유연성은 특히 en→zh, en→ja, en→ko(아시아 언어는 더 짧게 실행됨)에서 중요합니다. de→en, ja→en(더 길게 실행됨); ar/he/ur(RTL + 레지스터 이동).
선택 사항(관련이 있는 경우에만 질문):
- 용어집 / 번역 금지 용어. 기업 또는 기술 콘텐츠의 경우 질문: "원래 언어로 유지해야 할 제품 이름, 회사 이름 또는 전문 용어가 있습니까?" HeyGen은 현재 하드 용어집을 허용하지 않으므로, 이는 중요도가 높은 경우 교정 단계(3단계-교정)에 대한 지침이 됩니다.
- 부분 번역. 사용자가 특정 세그먼트(예: "인트로만", "1:30부터 4:00까지")를 언급하는 경우
start_time과end_time을 초 단위로 캡처하세요. - 최종 렌더링 전에 교정하시겠습니까? 기본값 OFF(더 빠르고, 승인 절차가 적음). 기본값 ON: 긴 비디오(>3분), 기업/브랜드 콘텐츠, 중요도가 높은 법률/의료/교육 콘텐츠, 사용자가 원어로 읽는 언어(확인 가능). 질문: "최종 렌더링 전에 자막을 검토하고 편집하시겠습니까? 약 5분 정도 더 걸리지만 잘못된 용어를 수정할 수 있습니다."
📖 로케일 쌍 문제(격식 레지스터, RTL 언어, 음조 압축, 립싱크 한계) → references/language-locale-guide.md
2단계 — 사전 점검
조용히 진행합니다. 사용자에게 알리지 않습니다. 순서대로 세 가지 확인.
확인 2a: 언어 유효성 검사.
MCP: list_video_translation_languages() (노출된 경우). 그렇지 않으면 CLI.
CLI: heygen video-translate languages list | jq -r '.data.languages[]'
목록에는 정확한 문자열("Spanish (Spain)", "Chinese (Mandarin, Simplified)", "Arabic (Saudi Arabia)")이 포함되어 있습니다. 사용자의 입력을 이러한 정확한 문자열에 대해 대소문자를 구분하지 않고 일치시킵니다. 사용자가 "Spanish"라고 말하면 기본값으로 "Spanish (Spain)"를 선택하고 4단계에서 확인합니다. "Chinese"라고 말하면 기본값으로 "Chinese (Mandarin, Simplified)"를 선택합니다. 지역을 지정하는 경우(예: "Mexican Spanish"), 매핑합니다("Spanish (Mexico)"). 일치하는 항목이 없으면 사용자에게 가장 가까운 옵션에서 선택하도록 요청합니다.
확인 2b: 소스 비디오 라우팅.
| 사용자가 제공한 소스 | 경로 |
|---|---|
공개 HTTPS URL(인증 없음, HEAD에 대해 비디오 MIME 반환) | {type: "url", url: "..."}으로 직접 전달 |
| 인증이 필요한 URL, 403, 404 또는 HTML 응답 | 사용자에게 알리고 공개 URL 또는 로컬 파일 요청 |
| 로컬 파일 경로 | heygen asset create --file <경로>(CLI) 또는 upload_asset(MCP)을 통해 업로드. 최대 32MB. 반환된 asset_id를 {type: "asset_id", asset_id: "..."}로 사용 |
| 기존 HeyGen asset_id | {type: "asset_id", asset_id: "..."}로 직접 전달 |
📖 자산 라우팅 에지 케이스(매우 큰 파일, 사전 서명된 URL, 인증이 필요한 소스) → references/asset-routing.md
확인 2c: 콘텐츠 프로필.
소스에 따라 하나의 프로필을 선택하세요. 다섯 가지를 모두 사용자에게 나열하지 마세요 — 조용히 제안하고 소스가 진정으로 모호한 경우에만 질문하세요(예: 음악이 많은 토킹헤드에서 음성 향상이 도움이 될지 알 수 없는 경우).
| 프로필 | 사용 시기 | 플래그 |
|---|---|---|
| 토킹헤드/발표자(기본값) | 한 사람이 카메라를 보고 말함, 깨끗한 오디오 | mode: precision, enable_speech_enhancement: true, enable_caption: true, enable_dynamic_duration: true, keep_the_same_format: true |
| 팟캐스트/오디오 전용 | 시각 자료가 정적이거나 중요하지 않거나 존재하지 않음 | mode: precision, translate_audio_only: true, enable_speech_enhancement: true, enable_caption: true |
| 음악/높은 사운드트랙 | 배경 음악이 음성을 방해함 | mode: precision, disable_music_track: true, enable_speech_enhancement: true, enable_dynamic_duration: true, keep_the_same_format: true |
| 다중 화자 | 두 명 이상의 서로 다른 화자 | 토킹헤드 기본값 + speaker_num: <개수>. 여기서 화자 수는 필수입니다 — 추측하지 마세요. |
| 기업/브랜드 | 브랜드 목소리, 용어 규율, 높은 중요도 | 토킹헤드 기본값 + (사용자가 있는 경우) brand_voice_id. 이 프로필에 대해서는 교정을 강력히 고려하세요. |
항상:
mode: "precision"(사용자가 명시적으로 "빠르게" / "빨리" / "속도"를 요청하지 않는 한).enable_dynamic_duration: 1단계의 길이 유연성 질문에 대한 사용자의 답변에 따라 설정합니다. 기본값true(권장) — 번역된 음성이 원본의 정확한 타이밍에 얽매이지 않고 숨 쉴 수 있도록 합니다. 사용자가 고정 길이 출력을 명시적으로 필요로 하는 경우에만false로 설정합니다. 음조 압축으로 인해 유연성은 특히 en→zh, en→ja, en→ko(아시아 언어는 더 짧게 실행됨)에서 중요합니다. de→en, ja→en(더 길게 실행됨); ar/he/ur(RTL + 레지스터 이동).keep_the_same_format: true— 시각적 번역의 경우 소스의 해상도와 비트 전송률을 유지하여 더빙된 비디오가 원본의 인코딩과 일치하도록 합니다.enable_watermark: false(기본값).
3단계 — 제출 + 폴링
조용히 진행합니다. 백그라운드 작업. 다음 경우에만 알림: (a) 언어별 완료, (b) 언어별 심각한 오류, (c) 5분 이상 진행 확인.
분기:
- 표준 경로(교정 = OFF): 번역 제출, 백그라운드 폴링, 전달.
- 교정 경로(교정 = ON): 교정 세션 생성 → SRT 다운로드 → 사용자 편집 또는 지원 → 편집된 SRT 업로드 → 최종 생성 → 백그라운드 폴링 → 전달.
표준 경로
배치 구문(--output-languages는 여러 개 허용)을 사용하여 대상 언어당 하나의 작업을 제출합니다.
MCP (현재 작성 시점에서는 단일 언어만 지원):
create_video_translation(
video={type, url|asset_id},
output_languages=["Spanish (Spain)"],
mode="precision",
enable_speech_enhancement=true,
enable_caption=true,
enable_dynamic_duration=true,
keep_the_same_format=true,
speaker_num=<n>, # 다중 화자가 알려진 경우에만
)
CLI:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--enable-speech-enhancement \
--enable-caption \
--enable-dynamic-duration \
--keep-the-same-format
CLI 배치 제출:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--enable-speech-enhancement \
--enable-caption \
--enable-dynamic-duration \
--keep-the-same-format
--wait 플래그를 추가하여 작업이 완료될 때까지 차단할 수 있습니다 (기본 시간 초과 20분).
--wait와 함께 배치 제출:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--enable-speech-enhancement \
--enable-caption \
--enable-dynamic-duration \
--keep-the-same-format \
--wait
상태 폴링
작업 상태를 확인하려면:
CLI:
heygen video-translate get <translation_id>
MCP:
get_video_translation(translation_id="<id>")
JSON 응답에는 status 필드가 포함됩니다: pending, processing, completed, failed.
교정 경로
교정이 활성화된 경우:
-
교정 세션 생성 CLI:
heygen video-translate proofreads create -d '{"translation_id":"<id>"}' -
교정 상태 확인 CLI:
heygen video-translate proofreads get <proofread_id> -
SRT 다운로드 CLI:
heygen video-translate proofreads srt get <proofread_id> -
편집된 SRT 업로드 CLI:
heygen video-translate proofreads srt update <proofread_id> -f <edited.srt> -
최종 비디오 생성 CLI:
heygen video-translate proofreads generate <proofread_id>
4단계 — 전달
최종 비디오 링크와 한 줄 요약을 보냅니다. 형식:
"✅ 비디오가 [언어]로 번역되어 준비되었습니다: [링크] ([길이], [모드])"
예: "✅ 비디오가 스페인어(스페인)로 번역되어 준비되었습니다: https://app.heygen.com/video/XXXXX (3분 42초, 정밀 모드)"
오류가 발생한 경우:
"❌ 번역에 실패했습니다: [간결한 오류 메시지]"
오류 처리
일반적인 오류 및 권장 조치:
| 오류 | 가능한 원인 | 조치 |
|---|---|---|
| 인증 실패 | API 키가 유효하지 않거나 만료됨 | heygen auth login으로 다시 인증 |
| 지원되지 않는 언어 | 언어가 지원 목록에 없음 | heygen video-translate languages list로 지원 언어 확인 |
| 비디오 크기 초과 | 파일이 32MB보다 큼 | 파일을 압축하거나 공개 URL 사용 |
| 비디오 형식이 잘못됨 | 지원되지 않는 비디오 코덱 또는 형식 | MP4, MOV, AVI로 변환 |
| 시간 초과 | 번역 시간이 20분 초과 | --wait 시간 초과 값을 늘리거나 수동으로 폴링 |
자세한 문제 해결은 references/troubleshooting.md를 참조하세요.
언어 지원
지원되는 언어의 전체 목록을 보려면:
CLI:
heygen video-translate languages list
MCP:
list_video_translation_languages()
모범 사례
- 오디오 품질 — 최상의 결과를 위해 깨끗하고 배경 소음이 없는 오디오로 시작하세요.
- 화자 수 — 다중 화자 비디오의 경우 항상 정확한 화자 수를 제공하세요.
- 동적 지속 시간 — 더 자연스러운 결과를 위해 활성화하는 것이 좋습니다.
- 교정 — 중요한 콘텐츠의 경우 최종 렌더링 전에 자막을 검토하세요.
- 자막 — 자막을 활성화하면 접근성과 청중 이해도가 향상됩니다.
제한 사항
- 최대 비디오 길이: 30분
- 최대 파일 크기: 32MB(로컬 업로드의 경우, URL의 경우 제한 없음)
- 지원되는 입력 형식: MP4, MOV, AVI
- 최대 출력 언어: 요청당 50개
- 립싱크 정확도는 소스 비디오 품질과 화자 가시성에 따라 다릅니다.