ElevenLabs 더빙은(는) 무엇을 하나요?

오디오 또는 비디오를 원래 화자의 목소리를 유지하면서 다른 언어로 더빙합니다. 파일 또는 URL에서 프로젝트를 만들고, 소스 대본을 검토 및 편집하고, 하나 이상의 대상 언어를 추가하고, 세그먼트별로 번역을 다듬고, 출력을 재생성합니다.

중요: Dubbing Projects API를 사용하세요 — SDK에서는 elevenlabs.dubbing.project.*, REST 엔드포인트에서는 /v1/dubbing/project를 사용합니다. 기존 v1 더빙 API(client.dubbing.create(), client.dubbing.get(), client.dubbing.audio.get() 또는 /v1/dubbing 경로)는 사용하지 마십시오. 이는 API 참조에서 Legacy 아래에 있는 이전 더빙 API입니다.

설정 (코드 작성 전): 이 프로젝트에 ELEVENLABS_API_KEY가 설정되지 않은 경우, 앱 폴더에서 npx -y @elevenlabs/cli@latest onboard init를 실행하고 출력되는 지침을 따르세요. 사용자를 로그인하고 프로젝트용 키를 저장하므로 수동으로 복사할 필요가 없습니다. 그렇지 않으면 설치 가이드를 참조하세요. elevenlabs CLI와 SDK는 ELEVENLABS_API_KEY를 자동으로 읽습니다. REST 기본 URL은 https://api.elevenlabs.io이며, xi-api-key 헤더에 API 키를 포함하세요.

개념

개념	의미
프로젝트	하나의 미디어 소스(파일 또는 URL)와 해당 소스 대본. 한 번 준비(전사)된 후, 언어를 추가하는 동안 `ready` 상태로 유지됩니다.
소스 대본	소스에서 전사된 편집 가능한 세그먼트(텍스트, 화자, 시간). 모든 언어가 번역되는 단일 진실 공급원입니다.
언어 (대상)	하나의 더빙 출력 언어. 각 언어는 자체 대본(소스 세그먼트 + 세그먼트별 번역)과 자체 더빙 오디오 출력을 가집니다.
리비전	독립적인 단조 증가 카운터. 프로젝트의 `revision`은 소스 대본 편집 시 증가합니다. 언어의 `revision`은 해당 언어의 번역 편집 또는 이에 영향을 미치는 소스 편집 시 증가합니다. 언어의 `output_revision`은 현재 오디오가 생성된 리비전입니다. `revision`보다 낮으면 출력이 최신 상태가 아닙니다.

권장 작업 순서: 언어를 추가하기 전에 소스 대본을 최종 확정하세요. 번역은 소스에서 생성되므로, 먼저 소스를 수정하면 모든 언어가 올바른 텍스트에서 시작됩니다. 언어가 완료된 후 소스를 편집하면 stale(부실) 상태가 되며 (유료) 재생성이 필요합니다.

엔터프라이즈: 대본 편집 및 재생성은 엔터프라이즈 워크스페이스에서만 사용할 수 있습니다. 프로젝트 생성, 언어 추가 및 더빙 다운로드는 모든 요금제에서 가능합니다.

워크플로

파일 또는 URL에서 프로젝트 생성 → queued
프로젝트가 ready가 될 때까지 폴링
소스 대본 검토 및 최종 확정 (세그먼트 편집/추가/삭제)
대상당 하나의 언어 추가 → queued → processing → completed
completed 상태일 때 각 언어의 outputs.lossless_audio 다운로드
필요한 경우 세그먼트별로 번역 다듬기 → 언어가 stale 상태가 됨
언어 재생성 → 새 출력으로 다시 completed

빠른 시작 (Python)

import os
import time
import requests
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

# 1. 로컬 파일에서 프로젝트 생성 (또는 file 대신 source_url=... 사용)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Q3 마케팅 비디오",
    )

# 2. 소스 미디어가 전사될 때까지 대기
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("프로젝트 준비 실패")
    time.sleep(5)

# 3. 스페인어 대상 언어 추가
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. 더빙 생성이 완료될 때까지 대기
while True:
    language = elevenlabs.dubbing.project.language.get(
        project.project_id, language.language_id
    )
    if language.status == "completed":
        break
    if language.status == "failed":
        raise RuntimeError("더빙 생성 실패")
    time.sleep(5)

# 5. 더빙된 오디오 다운로드 (서명된 URL, 약 1시간 유효 — 새 URL을 얻으려면 언어를 다시 가져오세요)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

빠른 시작 (JavaScript)

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { writeFile } from "fs/promises";

const elevenlabs = new ElevenLabsClient();

// 1. 프로젝트 생성 (sourceUrl 예시, 파일 업로드도 지원)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Q3 마케팅 비디오",
});

// 2. 소스 미디어가 전사될 때까지 대기
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("프로젝트 준비 실패");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. 스페인어 대상 언어 추가
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. 더빙 생성이 완료될 때까지 대기
while (true) {
  language = await elevenlabs.dubbing.project.language.get(project.projectId, language.languageId);
  if (language.status === "completed") break;
  if (language.status === "failed") throw new Error("더빙 생성 실패");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. 서명된 URL에서 더빙된 오디오 다운로드
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

빠른 시작 (CLI)

elevenlabs CLI는 환경 변수 ELEVENLABS_API_KEY를 자동으로 읽습니다.

# 1. 프로젝트 생성 (URL에서 더빙하려면 --file 대신 --source-url "https://..." 사용)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. 상태가 "ready"가 될 때까지 폴링
elevenlabs dubbing project get --project-id proj_...

# 3. 대상 언어 추가
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. 언어가 "completed"가 될 때까지 폴링한 후 outputs.lossless_audio 다운로드
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

생성 옵션

elevenlabs dubbing project create (REST: POST /v1/dubbing/project, multipart/form-data)는 file 또는 source_url (둘 다 아님)을 사용합니다:

필드	필수	참고
`file`	file/source_url 중 하나	더빙할 소스 미디어 (오디오 또는 비디오), 최대 3 GiB
`source_url`	file/source_url 중 하나	소스 미디어를 가져올 공개 URL
`source_language`	아니요	ISO 639 코드 (예: `en`). 생략하면 자동 감지 — 감지된 언어는 소스 대본의 `language` 필드에 보고됩니다
`reference`	아니요	프로젝트를 식별하기 위한 자유 형식 레이블 (최대 500자)
`model_id`	아니요	`dubbing_v2` (기본값)
`target_language`	아니요	생성 시 첫 번째 언어 대상을 선택적으로 대기열에 추가, 더 추가하려면 `language.create` 사용
`keyterms`	아니요	전사/번역을 편향시킬 용어 (제품/브랜드 이름). 최대 1000개 용어, 각 용어 최대 50자 및 5단어, `<>{}[]\` 허용되지 않음. multipart에서 용어당 필드를 한 번 반복

소스 대본 편집

프로젝트가 ready 상태가 되면 대본을 읽은 후 언어를 추가하기 전에 수정하세요. 모든 편집은 프로젝트의 revision을 증가시킵니다. 각 세그먼트에는 편집 또는 삭제에 사용되는 안정적인 id가 있습니다. (엔터프라이즈 워크스페이스 전용.)

# 소스 대본 읽기
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# 세그먼트 텍스트 수정 — 변경할 필드만 전송 (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="최신 제품 데모에 오신 것을 환영합니다.",
)

# 세그먼트 추가 (기존 speaker_id를 재사용하면 해당 화자의 목소리로 더빙됨)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="시청해 주셔서 감사합니다.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

# 세그먼트 삭제
elevenlabs.dubbing.project.transcript.delete_segment(project_id, segment_id=added.segment.id)

CLI를 통해: elevenlabs dubbing project transcript get --project-id proj_..., 그런 다음 변경된 필드만으로 세그먼트 업데이트 (--text, --speaker-id, --start-s, --end-s):

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "최신 제품 데모에 오신 것을 환영합니다."

번역 다듬기 및 재생성

언어의 대본은 각 소스 세그먼트를 해당 translation과 짝짓습니다 (null = 아직 번역되지 않음, 세그먼트 ID는 소스와 일치). 단일 번역을 편집한 다음 재생성합니다. (엔터프라이즈 워크스페이스 전용.)

# 언어의 번역 읽기
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# 단일 번역 다듬기 (translation=None을 전달하여 지우고 재번역 표시)
elevenlabs.dubbing.project.language.transcript.update_segment(
    project_id,
    language_id,
    segment_id=target.segments[0].id,
    translation="Bienvenido a nuestra última demostración de producto.",
)

# 현재 대본에서 더빙 재생성 (생성과 동일하게 과금)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

CLI를 통해: elevenlabs dubbing project language transcript update_segment --project-id proj_... --language-id lang_... --segment-id seg_... --translation "...", 그런 다음 elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... (202 Accepted 반환).

번역 편집은 해당 언어에만 영향을 미칩니다. 편집 후 completed 언어는 stale 상태가 됩니다. 재생성할 때까지 이전 출력을 계속 제공합니다. completed가 될 때까지 폴링하면 output_revision이 revision과 같아지고 outputs.lossless_audio가 현재 대본을 반영합니다.

여러 언어로 더빙

언어당 하나의 대상을 추가하세요. 각각 독립적으로 생성됩니다. 하나씩 폴링하는 대신 language.list로 모두 추적하세요:

for lang in ["es", "fr", "de", "ja"]:
    elevenlabs.dubbing.project.language.create(project_id, target_language=lang)

while True:
    result = elevenlabs.dubbing.project.language.list(project_id)
    if not any(l.status in ("queued", "processing") for l in result.languages):
        break
    time.sleep(5)

상태

프로젝트:

상태	의미
`queued`	생성됨. 소스 가져오기 + 준비가 대기열에 추가됨
`preparing`	준비(전사) 실행 중
`ready`	소스 대본 사용 가능, 언어 추가/생성 가능. 프로젝트는 `ready` 상태로 유지됨 — 언어별 진행은 언어에 기록
`failed`	준비 실패 (예: 소스를 가져오거나 디코딩할 수 없음)

언어:

상태	의미
`queued`	프로젝트가 `ready`가 되거나 생성 작업자가 할당되기를 기다리는 중
`processing`	더빙 생성 중
`completed`	완료됨. `outputs`에 서명된 다운로드 URL이 채워짐 (약 1시간 유효 — 새 URL을 얻으려면 다시 가져오세요)
`stale`	이전에 완료되었지만 대본이 변경됨. 재생성될 때까지 마지막 출력 유지
`failed`	생성 실패

프로젝트가 ready가 되기 전에 언어를 추가할 수 있습니다. 언어는 queued 상태로 유지되다가 프로젝트가 ready가 되면 자동으로 시작됩니다. 언어 추가 시 선택적 model_id (프로젝트의 기본값 사용) 및 voice_settings (예: {"cloning_strength": 7}, 범위 0–10, 기본값 7 — 더빙된 화자가 소스 목소리를 복제하는 강도 제어)를 허용합니다.

오류 처리

401: 잘못된 API 키
409 Conflict 재생성 시: 프로젝트가 ready 상태가 아니거나 언어가 안정되지 않음 (예: 이미 생성 중) — 기다렸다가 재시도
만료된 다운로드 URL: outputs.lossless_audio는 서명되어 있으며 약 1시간 유효 — 새 URL을 얻으려면 언어를 다시 가져오세요
대본 편집 / 재생성 불가: 이러한 엔드포인트는 엔터프라이즈 전용입니다. 다른 요금제에서는 최종 확정된 소스로 프로젝트를 만들고 언어를 직접 추가하세요

참조

설치 가이드
API 참조 — 전체 요청/응답 스키마 및 SDK 메서드 이름이 있는 모든 엔드포인트

ElevenLabs 더빙