> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 더빙 음성 복제 > 명시적 허가를 받은, 본인 소유의 업로드된 오디오 샘플로 맞춤형 동영상 더빙 음성을 생성하고 저장합니다. 앱의 맞춤 음성 슬롯 한도를 적용하며 오디오 예제를 포함합니다. 중복 생성을 방지하려면 requestId를 재사용하세요. 명시적 허가를 받은, 본인 소유의 업로드된 오디오 샘플로 맞춤형 동영상 더빙 음성을 생성하고 저장합니다. 앱의 맞춤 음성 슬롯 한도를 적용하며 오디오 예제를 포함합니다. 중복 생성을 방지하려면 requestId를 재사용하세요. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/dubbing_voices_clone ``` ## 인증 및 권한 이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다. 필요한 권한: `voices:write`. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다. ## 매개변수 전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 UUID v4를 직접 제공하세요. 형식: "uuid". 패턴: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`. 텍스트 값입니다. 최소 길이: 1. 최대 길이: 80. 텍스트 값입니다. 최소 길이: 1. 최대 길이: 1024. 불리언 값입니다. 필수 값: true. 아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다. ```json theme={null} { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hasPermission": { "type": "boolean", "const": true } }, "required": ["name", "fileKey", "hasPermission"], "additionalProperties": false } ``` ## 멱등성 각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요. ## 요청 예제 예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/dubbing_voices_clone' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","name":"Studio narrator","fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav","hasPermission":true}' ``` ```javascript JavaScript theme={null} const input = { requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91', name: 'Studio narrator', fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav', hasPermission: true, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/dubbing_voices_clone', { method: 'POST', headers: { 'x-api-key': process.env.VOICECHEAP_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(input), }); const body = await response.json(); if (!response.ok) throw new Error(body.code + ': ' + body.message); console.log(body); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/dubbing_voices_clone", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "name": "Studio narrator", "fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav", "hasPermission": True}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## 응답 이 작업은 실행 중에 HTTP 202를 반환합니다. requestId를 저장하고 해당 식별자와 원래 작업 이름으로 action\_request\_get을 폴링하세요. 폴링 상태는 running, completed, failed, interrupted입니다. 완료된 결과가 별도의 미디어 작업을 가리킬 수 있으므로 해당 작업의 상태 또는 출력 액션을 이어서 사용하세요. ID, 이름 및 선택적 오디오 예시를 포함한 저장된 사용자 지정 더빙 음성입니다. TTS 방식의 voice 또는 cloneUsage 래퍼는 없습니다. ```json HTTP 202 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "status": "running", "pollAction": "action_request_get", "pollAfterSeconds": 5 }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 200 theme={null} { "data": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ## 결과 필드 | 필드 | 설명 | | - | - | | `data.id` | 저장된 더빙 음성의 불투명 ID입니다. | | `data.name` | 저장된 음성의 표시 이름입니다. | | `data.audioExampleUrl` | 선택 사항인 재생 가능한 예시 오디오 URL입니다. 목록 및 단일 조회 응답에서는 previewUrl로 제공됩니다. | ## 이 요청 복구 및 폴링 연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요. ```bash theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"dubbing_voices_clone"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" } } } ``` ## 작업 참고 사항 * 이 변경 작업에 UUID v4 requestId를 사용하고 재시도 시 동일한 인수와 함께 재사용하세요. 장시간 실행되는 액션은 먼저 running 요청을 반환합니다. 이 예시는 action\_request\_get에서 얻을 수 있는 완료된 핸들러 결과입니다. * 이 액션은 본인 소유의 완료된 오디오 업로드 하나를 받으며 JSON 불리언으로 hasPermission: true가 필요합니다. 원격 URL이나 다른 계정의 fileKey는 허용하지 않습니다. * 지원되는 샘플 확장자는 AAC, AC3, EAC3, FLAC, M4A, X-M4A, MP2, MP3, OGG 및 WAV입니다. 파일은 비어 있지 않고 읽을 수 있는 오디오여야 하며 요금제의 업로드 한도 이내이면서 최대 250,000,000바이트(250 MB)여야 합니다. * 전용 voices*upload*\* 계열은 더 엄격합니다. MP3, WAV, M4A, OGG 또는 Opus만 지원하며 업로드당 최대 20 MiB입니다. 해당 업로드 계열에서 허용된 파일도 이 더빙 액션이 지원하는 샘플 유형과 일치해야 합니다. 여기서는 Opus를 지원하지 않습니다. * name은 앞뒤 공백 제거 후 1–80자여야 하며 제어 문자를 포함할 수 없습니다. * TTS 음성 복제의 합산 샘플 10–120초 규칙은 이 액션에 적용되지 않습니다. 샘플의 길이를 읽어낼 수 있어야 하며 그 값은 양수이고 45분을 초과해서는 안 됩니다. 오디오는 이 한도에 맞춰 자동으로 잘리지 않습니다. * 계정의 저장된 사용자 지정 더빙 음성 슬롯 허용량을 사용합니다. 업데이트된 cloneUsage는 dubbing\_voices\_list를 호출해 확인하세요. 복제 결과 자체에는 포함되지 않습니다. * 더빙에는 반환된 불투명 id를 사용하세요. clone: 접두사가 없으며 TTS 음성 선택에 사용할 수 없습니다. * 음성 합성 기록과 사용자 지정 음성은 인증된 계정에 속합니다. 팀 결제를 사용해도 다른 멤버의 음성 합성 결과나 음성에 접근할 수 없습니다. ## 사용량 성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다. ## 오류 | HTTP 상태 | 코드 | 의미 또는 복구 방법 | | - | - | - | | 400 | `BAD_REQUEST` | 샘플에서 읽을 수 있는 양수 길이를 확인할 수 없거나, 더빙 복제 길이 제한인 45분을 초과하거나, 너무 길어서 거부되었습니다. | | 400 | `CREDENTIAL_IN_QUERY` | 자격 증명이 access\_token 또는 api\_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요. | | 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key 헤더와 본문의 requestId 필드가 일치해야 합니다. | | 400 | `INVALID_REQUEST_ID` | UUID v4인 requestId 또는 Idempotency-Key를 제공하세요. | | 400 | `VALIDATION_ERROR` | 입력이 액션 스키마와 일치하지 않습니다. 필드 오류는 details를 확인하세요. | | 400 | `VOICE_NAME_INVALID` | 이름이 비어 있거나, 너무 길거나, 제어 문자가 포함되어 있습니다. | | 400 | `VOICE_SAMPLE_INVALID_SIZE` | 샘플이 비어 있거나, 실제 바이트가 선언된 크기와 일치하지 않거나, 현재 플랜 한도 또는 250 MB를 초과합니다. | | 400 | `VOICE_SAMPLE_INVALID_TYPE` | 샘플 파일명이 지원되는 더빙 오디오 형식이 아닙니다. | | 400 | `VOICE_SAMPLE_NOT_OWNED` | 업로드된 샘플이 안전하지 않거나 인증된 계정에 속하지 않습니다. | | 401 | `API_KEY_EXPIRED` | API 키가 만료되었습니다. | | 401 | `INVALID_API_KEY` | 유효하고 만료되지 않은 API 키를 제공하세요. | | 401 | `INVALID_CREDENTIAL` | Authorization 헤더의 형식이 잘못되었거나 x-api-key와 충돌합니다. | | 401 | `MISSING_CREDENTIAL` | 사용 가능한 헤더 자격 증명이 전달되지 않았거나 4096자를 초과했습니다. | | 401 | `USER_NOT_FOUND` | 이 자격 증명에 연결된 계정이 더 이상 존재하지 않습니다. | | 403 | `ACCOUNT_UNAVAILABLE` | 작업을 수행하는 계정 또는 결제 계정을 사용할 수 없거나 해당 계정이 삭제 중입니다. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | 이 자격 증명의 사용자가 둘 이상의 팀에 속해 있어 청구 컨텍스트가 모호합니다. | | 403 | `INSUFFICIENT_SCOPE` | 필요한 모든 권한을 부여하거나 다른 자격 증명을 사용하세요. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | 계정의 통합 한도를 확인할 수 없습니다. | | 403 | `SUBSCRIPTION_REQUIRED` | 활성 유료 구독을 사용하세요. | | 403 | `TEAM_OWNER_NOT_FOUND` | 실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | 이 계정에서는 이미 10개의 연동 액션이 실행 중입니다. 새 액션을 시작하기 전에 기존 요청을 폴링하세요. | | 409 | `DUBBING_VOICE_LIMIT_REACHED` | 사용자 지정 더빙 음성 저장 슬롯이 모두 사용 중입니다. | | 409 | `IDEMPOTENCY_CONFLICT` | 이 requestId는 이미 다른 더빙 음성 입력에 사용되었습니다. | | 409 | `VOICE_MUTATION_IN_PROGRESS` | 이 계정에서 다른 더빙 음성 변경 작업이 실행 중입니다. | | 409 | `VOICE_MUTATION_LEASE_LOST` | 변경 작업이 확보했던 실행 처리 권한을 잃었습니다. 다시 시도하기 전에 요청 상태와 저장된 음성을 확인하세요. | | 409 | `VOICE_REQUEST_ALREADY_STARTED` | 이 음성 요청은 이전에 시작되었지만 확인된 최종 결과가 없습니다. 다른 요청을 시작하기 전에 음성 목록과 요청 상태를 확인하세요. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 월간 한도가 초기화될 때까지 기다리거나 요금제를 변경하세요. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After가 있으면 지정된 시간만큼 기다리고 백오프를 적용하세요. | | 500 | `INTERNAL_ERROR` | 음성 액션을 완료할 수 없습니다. 새 변경 작업을 시작하기 전에 요청 상태와 저장된 음성을 확인하세요. | | 502 | `INTERNAL_ERROR` | 액션을 완료할 수 없거나 결과를 확인할 수 없습니다. 다른 생성을 시작하기 전에 요청 상태와 리소스 이력을 확인하세요. | | 503 | `ACTION_RESULT_UNAVAILABLE` | 액션은 실행되었지만 결과를 저장할 수 없습니다. 새 생성을 시작하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. | | 503 | `SERVER_RESTARTING` | 서버가 다시 시작 중입니다. 잠시 후 재시도하고, 변경 작업의 경우 동일한 요청 식별자를 유지하세요. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["voices:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.