ElevenLabs 더빙

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

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

설정: 설치 가이드를 참조하세요. REST 기본 URL은 https://api.elevenlabs.io이며 xi-api-key 헤더에 API 키를 포함합니다. SDK는 ELEVENLABS_API_KEY를 자동으로 읽습니다.

개념

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

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

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

워크플로우

프로젝트 생성 (파일 또는 URL에서) → queued
프로젝트 폴링 (ready 상태가 될 때까지)
소스 대본 검토 및 최종 확정 (세그먼트 편집/추가/삭제)
언어 추가 (대상 언어당 하나씩) → queued → processing → completed
각 언어의 outputs.lossless_audio 다운로드 (completed 상태일 때)
필요시 세그먼트별 번역 다듬기 → 언어가 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()));

빠른 시작 (cURL)

# 1. 프로젝트 생성 (URL에서 더빙하려면 -F "source_url=https://..." 사용)
curl -X POST "https://api.elevenlabs.io/v1/dubbing/project" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "[email protected]" \
  -F "source_language=en"
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. 상태가 "ready"가 될 때까지 폴링
curl "https://api.elevenlabs.io/v1/dubbing/project/proj_..." \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

# 3. 대상 언어 추가
curl -X POST "https://api.elevenlabs.io/v1/dubbing/project/proj_.../language" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_language": "es"}'

# 4. 언어가 "completed"가 될 때까지 폴링한 후, outputs.lossless_audio 다운로드
curl "https://api.elevenlabs.io/v1/dubbing/project/proj_.../language/lang_..." \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

생성 옵션

POST /v1/dubbing/project는 file 또는 source_url(둘 중 하나)을 multipart/form-data로 받습니다.

필드	필수 여부	설명
`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`	아니요	전사/번역을 특정 용어(제품/브랜드 이름)로 편향시키는 용어. 최대 100개 용어, 각 200자. 멀티파트에서 용어당 한 번씩 필드를 반복하세요.

소스 대본 편집

프로젝트가 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)

REST를 통해: GET /v1/dubbing/project/{project_id}/transcript, 그 다음 변경된 필드만 PATCH .../transcript/segment/{segment_id}:

curl -X PATCH "https://api.elevenlabs.io/v1/dubbing/project/{project_id}/transcript/segment/{segment_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"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)

REST를 통해: PATCH /v1/dubbing/project/{project_id}/language/{language_id}/transcript/segment/{segment_id} with {"translation": "..."}, 그 다음 POST .../language/{language_id}/transcript/regenerate (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 영상/음성 더빙 (개인 브랜드)

음성 더빙 (개인 브랜드)란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

ElevenLabs 더빙

개념

워크플로우

빠른 시작 (Python)

빠른 시작 (JavaScript)

빠른 시작 (cURL)

생성 옵션

소스 대본 편집

번역 다듬기 및 재생성

여러 언어로 더빙

상태

오류 처리

참조

관련 스킬

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code