Skip to main content
POST
명시적 허가를 받은, 본인 소유의 업로드된 오디오 1~3개로 임시 음성 복제 미리 보기를 생성합니다. 앱의 복제 체험 허용량을 사용합니다. 계속 사용하려면 선택한 미리 보기가 만료되기 전에 저장하세요.

인증 및 권한

string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다.
필요한 권한: voices:write. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

매개변수

string
전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 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}$.
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 80.
array
필수
값 목록입니다. 항목 구조는 전체 입력 스키마를 참고하세요.최소 항목 수: 1. 최대 항목 수: 3.
boolean
필수
모든 샘플에 포함된 음성의 당사자로부터 음성 복제 권한을 받았는지 확인하세요.필수 값: true.
boolean
불리언 값입니다.기본값: false.
string
텍스트 값입니다.최대 길이: 35. 패턴: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

멱등성

각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.

요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

응답

이 작업은 실행 중에 HTTP 202를 반환합니다. requestId를 저장하고 해당 식별자와 원래 작업 이름으로 action_request_get을 폴링하세요. 폴링 상태는 running, completed, failed, interrupted입니다. 완료된 결과가 별도의 미디어 작업을 가리킬 수 있으므로 해당 작업의 상태 또는 출력 액션을 이어서 사용하세요. 새 복제 후보를 포함한 모든 활성 미저장 음성 미리보기와 업데이트된 생성 허용량입니다.

결과 필드

이 요청 복구 및 폴링

연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.
HTTP 200

작업 참고 사항

  • 이 변경 작업에 UUID v4 requestId를 사용하고 재시도 시 동일한 인수와 함께 재사용하세요. 장시간 실행되는 액션은 먼저 running 요청을 반환합니다. 이 예시는 action_request_get에서 얻을 수 있는 완료된 핸들러 결과입니다.
  • 소유한 오디오 샘플 1–3개를 업로드하고 완료된 fileKey 값을 사용하세요. 지원되는 샘플 형식은 MP3, WAV, M4A, OGG 및 Opus입니다. 각 파일은 비어 있지 않아야 하며 최대 20 MiB(20,971,520바이트)여야 합니다. 원격 URL과 다른 계정의 업로드는 허용되지 않습니다.
  • 샘플에는 읽을 수 있는 오디오가 총 10초 이상 120초 이하여야 합니다. trimToMaxDuration의 기본값은 false입니다. 총 길이가 120초를 초과하는 샘플을 비례적으로 잘라내려면 true로 설정하세요.
  • hasPermission은 모든 샘플에 대한 권한을 확인하는 JSON 불리언 true여야 합니다. “true”와 같은 문자열 값은 거부됩니다.
  • name은 앞뒤 공백 제거 후 1–80자여야 합니다. 선택 사항인 language는 2–3개의 영문자로 된 코드와 선택적 하위 태그를 지원하며 최대 35자입니다.
  • 계정당 평생 한 번 제공되는 복제 미리보기 체험을 사용합니다. 이 미리보기를 생성해도 재사용 가능한 TTS 음성이 저장되거나 음성 저장 슬롯이 사용되지 않습니다.
  • 새 복제 후보는 kind: clone이며 24시간 동안 유지됩니다. 재생은 약 10초로 제한됩니다.
  • 응답에는 저장되지 않은 모든 활성 미리보기가 포함됩니다. voices_preview_get으로 재생 URL을 갱신한 다음, 유료 플랜에서 voices_save_preview로 선택한 후보를 보관하세요.
  • 지원되는 스크립트가 있으면 language가 미리보기 스크립트를 선택합니다. 업로드한 샘플을 번역하라는 요청이 아닙니다.
  • 음성 합성 기록과 사용자 지정 음성은 인증된 계정에 속합니다. 팀 결제를 사용해도 다른 멤버의 음성 합성 결과나 음성에 접근할 수 없습니다.

사용량

성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.

오류