Skip to main content
프로젝트 더빙

프로젝트 더빙

직접 제공한 번역 SRT로 기존 프로젝트의 음성을 생성하고 출력을 믹스합니다. 이 엔드포인트에서 VoiceCheap은 아무것도 번역하지 않습니다. 번역 엔진, SmartSync 재작성, 용어집 모두 사용하지 않습니다. 각 큐는 프로젝트 전사의 해당 세그먼트에서 그대로 읽힌 뒤, 일반 번역과 같이 원본 배경음, 자막, 선택적 립싱크와 믹스됩니다. 번역을 다른 곳에서 만드는 경우(사람 번역가, 자체 도구, 자동화 흐름)에 사용하고, VoiceCheap에는 음성 생성만 맡깁니다. 실행은 비동기입니다. 번역 상태 가져오기를 폴링하거나 웹훅을 수신하세요.

사전 조건

  • 프로젝트가 존재하고 전사가 완료되어 있어야 합니다. 프로젝트 생성(전사만) 또는 번역 시작로 만든 뒤 transcriptionStatus: "success"을 기다리세요.
  • SRT는 프로젝트 전사를 모두 덮어야 합니다. 모든 전사 세그먼트에는 큐가 하나 이상 필요하고, 모든 큐는 어떤 세그먼트 위에 있어야 합니다. 프로젝트 대본 내보내기로 전사를 내보낸 뒤 타임코드를 유지한 채 큐마다 번역하세요.
  • 요청은 같은 미디어의 번역과 동일하게, 같은 크레딧 확인으로 청구됩니다. 립싱크 모드는 평소와 같이 추가 크레딧을 사용합니다.

동시성 제한

프로젝트 생성, 번역, 더빙은 모두 계정의 진행 중인 번역 한도(최대 10개, 계정에 따라 더 낮을 수 있음)를 확인합니다. 진행 중인 번역이나 더빙 작업만 한도를 차지하며, 전사 전용 프로젝트는 한도를 차지하지 않습니다. 한도에 도달하면 API는 CONCURRENT_TRANSLATION_LIMIT_REACHED(HTTP 429)를 반환합니다. 적용되는 한도는 details.limit에서 확인할 수 있습니다. 같은 프로젝트와 대상 언어로 실행 중인 작업이 있으면 두 번째 실행도 거부됩니다(TRANSLATION_ALREADY_IN_PROGRESS, HTTP 409).

요청

이 엔드포인트는 JSON 본문을 받습니다(Content-Type: application/json). 불리언과 숫자 옵션은 문자열이 아니라 JSON 값으로 보냅니다.

헤더

string
필수
귀하의 VoiceCheap API 키입니다. app.voicecheap.ai/page-api에서 키를 발급받으세요.

경로 매개변수

string
필수
프로젝트 생성 또는 번역 시작가 반환하는 프로젝트 식별자입니다.

본문 매개변수

string
필수
translatedSrt의 언어입니다. 소문자이며 번역 시작와 같은 목록에서 고릅니다. 프로젝트에 이 언어의 작업이 아직 없으면 하나가 만들어지고 언어가 프로젝트에 추가됩니다.
string
필수
최종 대상 언어 SRT 내용입니다(큐 번호, 타이밍 줄, 텍스트). 최대 1,000,000자입니다. 큐는 타임스탬프로 전사 세그먼트에 맞춰집니다. 세그먼트 시작 후 50ms 이내에 시작하는 큐는 그 세그먼트에, 그렇지 않으면 겹침이 가장 큰 세그먼트에 할당됩니다. 한 세그먼트의 여러 큐는 공백으로 이어집니다. 읽히는 각 세그먼트의 타이밍, 화자, 순서는 항상 프로젝트 전사에서 옵니다. 타임코드는 맞추는 데만 쓰입니다.
string
이제부터 이 프로젝트의 웹훅 이벤트를 받는 https 엔드포인트입니다. 계정에 설정된 엔드포인트를 덮어씁니다.기본값: 프로젝트에 이미 저장된 엔드포인트, 그다음 계정의 웹훅 엔드포인트.
boolean
생성된 음성 아래에 원본 배경 오디오(음악, 주변음)를 유지합니다.기본값: true
boolean
생성된 음성 아래에 원본 화자 음성을 작게 유지합니다.기본값: false
number
keepOriginalVoice가 켜져 있을 때 원본 음성 음량입니다. 1에서 70까지입니다.기본값: 30
string
음성 방식: cloning(프로젝트 화자의 음성을 복제) 또는 custom(카탈로그 음성이나 내가 저장한 사용자 지정 음성을 사용).기본값: cloning
string
voiceMode가 custom일 때 필수입니다. dubbing_voices_list에서 카탈로그 음성이나 인증된 계정이 저장한 사용자 지정 음성의 ID를 사용하세요. 팀 결제를 사용해도 다른 구성원이 저장한 음성에 접근할 수 없습니다.
string
keepBackgroundMusic가 켜져 있을 때의 음성 분리 모드입니다. studio 또는 realistic.기본값: studio
boolean
출력 영상에 자막을 굽습니다. 영상 프로젝트가 필요합니다.기본값: false
string
subtitles가 켜져 있을 때의 자막 텍스트입니다. translated(제공한 SRT) 또는 original(원본 전사).기본값: translated
string
더빙이 준비되면 립싱크를 실행합니다. standard, pro 또는 studio. 요금제, 길이, 크레딧 규칙은 번역 시작와 같습니다. 영상 프로젝트가 필요합니다.기본값: 립싱크를 건너뛰려면 이 필드를 생략하세요.
boolean
요청한 립싱크 실행에서 활성 화자 감지를 켭니다.기본값: false
object
음성 복제 미세 조정입니다. stability와 similarity를 0에서 1 사이로 둔 JSON 객체입니다. voiceMode: "cloning"일 때만 사용합니다. 각 값의 안내는 번역 시작를 참고하세요.
array
원본 언어로 남길 소스 시간 범위입니다. 형식은 [{ "startTime": 10.2, "endTime": 12.8 }]입니다. 영상 프로젝트와 keepBackgroundMusic: true가 필요하며 keepOriginalVoice와 함께 쓸 수 없고 전사 세그먼트와 겹칠 수 없습니다.

응답

boolean
필수
성공한 요청에서는 항상 true입니다.
string
필수
사람이 읽을 수 있는 확인 메시지입니다.
string
필수
더빙 중인 프로젝트입니다.
string
필수
targetLanguage에 사용하는 번역 작업입니다. 상태, 세부 정보, 전사 엔드포인트의 workId와 같습니다.
number
필수
처리 시간의 대략적인 추정치(분)입니다. 원본 미디어의 시작된 1분당 처리 5분입니다.
Response

실행 추적

더빙이 시작되면 프로젝트는 translation 워크플로로 전환되므로 번역 상태 가져오기가 새 실행을 따릅니다. status는 processing에서 success(translatedVideoUrl 및 translatedAudioUrl 포함) 또는 failed(error 포함)로 이동합니다. project.translation.completed 및 project.translation.failed 웹훅은 같은 targetLanguage와 함께 전송됩니다. 프로젝트 세부 정보 가져오기에서 번역본은 settings.dubbingMode: "dub-only"와 settings.smartSync: false를 보고합니다. POST 요청이 수락된 뒤 정렬 오류가 비동기적으로 보고됩니다. 상태 엔드포인트는 error.code와 error.message가 포함된 status: "failed"를 반환하고, project.translation.failed 웹훅에도 같은 코드와 메시지가 들어 있습니다. TRANSLATED_SRT_UNMATCHED_CUES의 메시지에는 일치하지 않은 큐 번호가, TRANSLATED_SRT_MISSING_SEGMENTS의 메시지에는 큐가 없는 세그먼트 인덱스가 표시됩니다. 이 비동기 응답에는 구조화된 details가 포함되지 않습니다. SRT를 수정하고 엔드포인트를 다시 호출하세요. 실패한 버전은 기록에 남고 새 버전이 생성됩니다.

속도 확인

프로젝트 대본 내보내기로 번역 전사를 JSON으로 내보내세요. 각 세그먼트에는 생성된 음성과 세그먼트 구간의 비율 finalSpeedFactor가 있습니다. 대략 1.3을 넘는 큐를 줄인 뒤 수정한 SRT로 더빙을 다시 실행하세요.

예시 흐름

일반적인 자동화(예를 들어 n8n 또는 Make 시나리오)는 엔드포인트를 다음과 같이 잇습니다.
  1. 미디어, targetLanguage, 명시적인 originalLanguage와 함께 POST /v1/projects(전사만).
  2. transcriptionStatus가 success가 될 때까지 GET /v1/translate/{projectId}/status를 폴링하거나 project.created 웹훅을 기다립니다.
  3. { "source": "original", "outputFormat": "srt" }와 함께 POST /v1/projects/{projectId}/transcript하고, 번호와 타임코드를 유지한 채 큐를 번역합니다.
  4. 번역한 SRT와 함께 POST /v1/projects/{projectId}/dub.
  5. status가 success가 될 때까지 상태 엔드포인트를 폴링하거나 project.translation.completed를 기다립니다.
  6. translatedVideoUrl를 다운로드합니다(립싱크를 요청했다면 lipSync.videoUrl).
  7. 출력을 저장한 뒤 DELETE /v1/translate/{projectId}.

오류

실행 중에 감지된 정렬 실패(TRANSLATED_SRT_UNMATCHED_CUES, TRANSLATED_SRT_MISSING_SEGMENTS)는 이 요청이 아니라 상태 엔드포인트와 실패 웹훅이 반환합니다.