사용 가이드
ElevenLabs Text to Dialogue 사용 가이드: dialogue 배열로 2인 대화 오디오 제출하기
2인 대본 분할에서 문장별 음색 요청까지, 현재 HiAPI 계약에 따라 제출하고 검수하기
이 페이지에서
먼저 해결하려는 것이 대화 합성인지 단일 낭독인지 확인하세요
소재가 2인(또는 다역할) 대화 대본이라면 가장 직접적인 방법은 보통 각 대사를 개별로 합성한 뒤 순서대로 이어 붙이는 것입니다. 이 방식의 문제는 납품 단계에서야 드러납니다. 문장마다 별도 오디오이므로 문장 간 휴지, 말 속도 연결, 음색 일관성을 이어 붙이는 계층에서 다시 보완해야 하며, 역할이 많아지면 이어 붙이는 순서와 음색 불일치가 주요 버그 원인이 됩니다.
elevenlabs/text-to-dialogue의 목적은 한 번의 요청으로 전체 대화를 표현하는 것입니다. 전체 대본을 dialogue 배열로 나누어 제출하면 모델이 한 번의 생성에서 다중 음색 대화를 완성하고, 출력은 하나의 완전한 오디오입니다. '여러 번의 단일 구간 합성 + 이어 붙이기'와 비교하면 역할 매핑과 행 순서를 모두 요청 본문 안에 담기 때문에, 검수 시에는 결과 하나만 확인하면 됩니다.
따라서 먼저 판단하세요:
- 내용이 동일 화자의 연속 낭독이라면 텍스트 음성 변환만 사용하면 되며
dialogue배열은 필요 없습니다; - 내용이 두 명 이상 역할이 교대하는 대화이고 전체 청취감이 통일되기를 원한다면 이 인터페이스의
dialogue배열을 사용해야 합니다; - 내용이 대화이지만 총 문자 수가 상한을 크게 초과한다면 의미 단위로 분할하여 구간별로 제출해야 하며, 문장별 합성으로 되돌아가서는 안 됩니다.
두 번째 유형에 해당한다고 판단했다면, 다음으로 배열 자체의 구조를 파악해야 합니다.

dialogue 배열의 구조: 각 행의 text와 voice
HiAPI 계약에서 elevenlabs/text-to-dialogue의 입력 핵심은 필수 필드 하나뿐입니다: dialogue. 이는 배열이며 최소 1개 항목이 있고, 각 요소는 한 행의 대화로 두 개의 필수 하위 필드를 포함합니다:
text: 해당 행 대사의 텍스트, 문자열, 최소 1자;voice: 해당 행에 사용할 음색, 문자열, 프리셋 음색 이름 또는voice_id를 입력할 수 있으며 기본값은EkK5I93UQWFDigLMpZcX입니다.
두 필드 모두 필수입니다. 기본 음색만 사용하려는 경우에도 voice를 명시적으로 작성하여 요청 본문이 스스로 설명되도록 하는 것이 좋습니다. 최소한의 2인 요청 형태는 다음과 같습니다:
{
"dialogue": [
{ "text": "그쪽 진행 상황은 어때요?", "voice": "EkK5I93UQWFDigLMpZcX" },
{ "text": "이번 주에 첫 버전을 낼 수 있어요.", "voice": "Z3R5wn05IrDiVCyEkUrK" },
{ "text": "좋아요, 그럼 제가 먼저 검수 체크리스트를 보내드릴게요.", "voice": "EkK5I93UQWFDigLMpZcX" }
]
}
배열의 순서가 곧 대화 순서이며, 인터페이스에는 별도의 '화자' 필드가 없습니다. 역할은 전적으로 voice로 구분됩니다. 이것이 전체 연동 과정에서 가장 먼저 설계해야 할 점입니다.

2인 대본을 문장별 항목으로 나누기
대본 텍스트에서 dialogue 배열로 가려면 고정된 파이프라인으로 처리하여 JSON을 손으로 작성하다 생기는 오류를 피하는 것이 좋습니다.
1단계: 행 단위로 나누고 화자 표시하기
대본을 '화자 + 대사'의 쌍 구조로 정리하고, 한 문장에 한 항목으로 만드세요. 두 역할의 대사를 하나의 text에 합치지 마세요. 그렇게 하면 한 요소에 voice 하나만 연결되므로 합친 뒤에는 역할을 구분할 수 없습니다. 내레이션, 괄호 안의 무대 지시는 대사가 아니므로 별도로 제거하고 text에 넣지 마세요.
2단계: 텍스트 정리
항목별로 확인하세요: 앞뒤 공백 제거, 문장 부호와 줄바꿈 통일, 빈 줄 삭제. text의 최소 길이 제약은 1자이며 빈 문자열은 곧바로 검증 실패를 일으킵니다. 어떤 행이 감탄사(예: '음', '맞아')만 있다면 유지해도 되지만, 정리 후 빈 문자열이 된다면 콘텐츠 담당자와 해당 행을 삭제할지 확인해야 합니다.
3단계: 역할 매핑을 만들고 배열 생성하기
각 화자 레이블을 고유 음색에 매핑한 뒤 행 순서대로 요소를 생성합니다. 의사 코드는 대략 다음과 같습니다:
speaker_voice = {
"A": "EkK5I93UQWFDigLMpZcX",
"B": "Z3R5wn05IrDiVCyEkUrK",
}
dialogue = [
{"text": line.text, "voice": speaker_voice[line.speaker]}
for line in script
]
자주 하는 실수
- 같은 역할이 두 곳에서 서로 다른 음색을 쓰면 청취감이 뚜렷하게 갈라집니다;
voice를 빠뜨려 전체가 기본 음색으로 되돌아가면 2인 대화가 '한 사람이 두 역할을 연기'하는 형태가 됩니다;- 배열 순서가 정렬이나 중복 제거 로직으로 뒤섞이면 대화 의미가 끊깁니다.
생성 후에는 먼저 앞쪽 몇 개 요소를 출력해 사람이 직접 확인한 뒤 문자 예산 단계로 넘어가세요.
음색 매핑 고정: 같은 역할은 하나의 voice만 사용
voice를 '고정'해야 하는 이유는 그것이 음색 자체를 결정할 뿐 아니라 '누가 말하고 있는지'라는 의미도 담당하기 때문입니다. 같은 역할이 전체 대화에서 서로 다른 두 voice 값을 가지면 청취자는 사람이 바뀌었다고 느낍니다. 반대로 두 역할이 같은 voice로 겹치면 대화의 구분성이 사라집니다.
실무에서는 각 행의 대사에 문자열 리터럴을 흩어 놓기보다 코드에 역할 대 음색 상수 매핑 테이블을 유지하는 것이 좋습니다:
const VOICE = {
host: "EkK5I93UQWFDigLMpZcX",
guest: "Z3R5wn05IrDiVCyEkUrK",
};
모든 행은 이 테이블에서만 값을 가져오므로, 대본의 줄바꿈이나 재배열이 일관성을 깨뜨리지 않습니다. voice는 프리셋 음색 이름 또는 voice_id를 지원합니다. 팀에 자체 음색 명명 체계가 있다면 설정 계층에서 한 번 변환하여 요청 시점에는 인터페이스가 인정하는 값으로 통일할 수 있습니다. 계약에 음색 열거형이 제시되어 있으므로 제출 전에 열거형으로 한 번 검증하면 철자 오류 같은 저급한 문제를 막을 수 있습니다. 열거형 외 값은 조용히 기본값으로 처리되지 않습니다.
또 하나 흔히 간과되는 점은 구간 간 안정성입니다. 총 문자 수가 상한을 넘어 여러 번의 요청으로 나누어야 할 때는 음색 매핑 테이블을 그대로 재사용하고, 새 요청에서 음색을 다시 고르지 마세요. 그렇지 않으면 같은 역할이 구간마다 다르게 들릴 수 있습니다.

문자 예산과 요청 분할
인터페이스에는 분량에 대한 강한 제약이 하나 있습니다: dialogue 배열 안의 모든 text 필드의 총 문자 수가 5000을 초과할 수 없습니다. 이는 배열 내 모든 텍스트의 합계이며, 단일 행 길이나 요소 개수가 아닙니다. 중국어, 영어, 문장 부호는 보통 모두 문자로 계산되므로 추정할 때는 가장 넓은 기준으로 여유를 두는 것이 좋습니다.
카운트 로직은 배열 생성 후, 요청 전송 전에 작성해야 합니다:
total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000
상한을 초과할 때 올바른 방법은 의미 경계를 기준으로 분할하여 여러 하위 대화로 나누고, 각각 제출하여 각각 오디오를 받은 뒤 업무 필요에 따라 조합하는 것입니다. 대사를 잘라내거나 문장을 삭제해서는 안 됩니다. 분할할 때 세 가지에 유의하세요:
- 분할 지점은 장면 전환이나 화제 전환 지점으로 선택하여, 문답 한 쌍을 두 번의 요청으로 쪼개지 않도록 합니다;
- 각 하위 구간을 별도로 카운트하며 마찬가지로 5000을 넘지 않게 합니다;
- 분할된 각 구간의 배열을 재구성할 때 기존 행 순서와 역할 음색 매핑을 유지합니다.
내용 자체가 긴 대화라면 콘텐츠 측에서 '막' 또는 '장' 단위로 구성하여 각 막이 자연스럽게 예산 안에 들어가도록 하면, 임시 분할로 인한 청취감 단절을 줄일 수 있습니다.
선택 파라미터: stability와 language_code
dialogue 외에도 인터페이스는 두 개의 선택 파라미터를 제공하며, 선택은 콘텐츠 유형에 따라 달라집니다.
stability
stability는 수치 파라미터로 0, 0.5, 1을 사용할 수 있으며 기본값은 0.5입니다. 의미는 음색 안정성입니다:
- 값이 작을수록 감정이 풍부하고 변화가 많아, 감정 기복이 있는 대화나 극적 콘텐츠에 적합합니다;
- 값이 클수록 출력이 안정적이고 일관되어, 브랜드 안내 방송이나 고객 응대 멘트처럼 통일된 청취감이 요구되는 장면에 적합합니다;
- 기본값 0.5는 둘 사이의 절충입니다.
이는 요청 전체 수준의 파라미터이며 행별 설정이 아닙니다. 같은 대화에서 역할 간 감정 차이가 클 때는 절충값을 받아들이거나, 구간을 나눌 때 서로 다른 stability를 사용해야 합니다.
language_code
language_code는 ISO 형식 언어 코드이며 기본값은 빈 문자열이고, 비워 두면 언어 자동 감지를 의미합니다. 콘텐츠 언어가 명확하고 감지 편차를 피하고 싶다면 명시적으로 지정하는 것이 더 안정적입니다. 예를 들어 중국어 콘텐츠에는 zh를 입력합니다. 계약에 전체 언어 코드 열거형이 제시되어 있으므로 제출 전에 한 번 검증하여 지원되지 않는 값이 전달되지 않도록 해야 합니다.
두 파라미터 모두 필수 항목이 아닙니다. 콘텐츠에 특별한 요구가 없다면 생략하고 기본 동작을 사용해도 충분합니다.
제출과 검수: 작업형 계약에 따라 확인하기
이 인터페이스는 작업 형태로 제출됩니다. 입력을 보내면 작업 결과를 받고, 그 결과를 중심으로 검수합니다. 이는 두 가지를 의미합니다.
첫째, 입력 계약은 직접 검증해야 합니다. 요청 전에 항목별로 확인하세요: dialogue는 배열이고 최소 1개 항목이 있는지; 각 항목에 비어 있지 않은 text와 voice가 동시에 있는지; 모든 text의 총 문자 수가 5000을 넘지 않는지; stability는 0/0.5/1만 사용하는지; language_code는 열거형에 속하거나 비어 있는지. 이러한 검사를 클라이언트에 두면 유효하지 않은 제출을 크게 줄일 수 있습니다.
둘째, 계약에 명시되지 않은 동작을 가정하지 마세요. 인터페이스 문서는 자동 재시도, 멱등 키, 실패 보상을 약속하지 않으므로 '같은 요청을 반복 제출'하는 것으로 안전장치를 삼지 마세요. 모든 제출은 독립적인 작업으로 간주되어야 합니다. 엔지니어링 관점의 안정적인 방법은 다음과 같습니다:
- 제출 전에 이번 요청의 입력 요약(배열 항목 수, 총 문자 수, 음색 매핑 버전)을 기록하여 사후 비교에 활용합니다;
- 결과를 받은 뒤 먼저 오디오가 사용 가능한지, 길이가 합리적인지, 역할이 구분되는지 확인한 후 하위 배포를 진행합니다;
- 재실행이 필요하면 검증되지 않은 이전 요청 본문을 재사용하지 말고 전체 입력 검증을 다시 거칩니다.
검수의 핵심은 '결과가 기대에 부합하는지'이며, 서버 내부 프로세스를 추측하는 것이 아닙니다. HiAPI에서는 elevenlabs/text-to-dialogue 모델 페이지에서 현재 계약을 확인한 뒤 시작할 수 있습니다.
출시 전 자체 점검 목록
아래 점검 세트를 제출 전 자동 절차로 고정하면 대부분의 실패 원인을 커버할 수 있습니다:
dialogue는 배열이고 요소 수가 ≥ 1인지;- 각 요소에
text와voice가 동시에 포함되고 둘 다 빈 문자열이 아닌지; - 각
voice가 계약 열거형 안에 있고, 같은 역할은 전체에서 같은 값만 사용하는지; - 배열 순서가 대본 행 순서와 일치하고 정렬이나 중복 제거 로직이 개입하지 않았는지;
- 모든
text의 총 문자 수가 ≤ 5000이고, 초과 내용은 의미 단위로 분할되었는지; - 명시적으로 설정한 경우
stability∈ {0, 0.5, 1},language_code∈ 열거형 또는 비어 있는지; - 입력 요약(항목 수, 문자 수, 매핑 버전)이 기록되어 검수 비교에 활용 가능한지.
목록 외에도 한 가지 경험 규칙이 있습니다. 먼저 짧은 샘플에서 엔드투엔드를 통과시킨 뒤 전체 대본으로 확장하세요. 역할 매핑과 문자 예산 두 가지 문제는 수십 행의 샘플에서도 드러나므로, 전체 콘텐츠를 제출한 뒤에야 발견할 필요가 없습니다.