Skip to main content
POST
원문과 번역문의 타이밍 변경을 함께 적용하도록 대기열에 추가합니다. 타이밍은 인접 세그먼트나 건너뛴 오디오와 겹칠 수 없습니다. segment_actions_list를 폴링하세요.

인증 및 권한

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

매개변수

string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴: ^[^/\\]+$.
integer
필수
정수 값입니다.최솟값: 0. 최댓값: 9007199254740991.
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}$.
number
필수
숫자 값입니다.최솟값: 0.
number
필수
숫자 값입니다.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

멱등성

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

요청 예제

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

응답

성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다. 원본 세그먼트와 번역된 세그먼트의 타이밍을 함께 편집하는 작업의 큐 접수 결과를 반환합니다.

결과 필드

이 요청 복구 및 폴링

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

작업 참고 사항

  • 의도한 편집에 UUID v4 requestId 하나를 사용하고, 재시도할 때는 동일한 인수와 함께 재사용하세요. jobId는 이 requestId와 같습니다.
  • 등록 시에는 완료가 아니라 started 또는 queued가 반환됩니다. completed, failed 또는 cancelled가 될 때까지 segment_actions_list를 폴링하며 items[].id가 jobId와 같은 항목을 확인한 다음 transcripts_get과 projects_get을 새로 조회하세요.
  • queue.revision은 대기열 상태를 추적하며 원본 세그먼트 구조 리비전이 아닙니다. 대기열 액션은 등록 시점의 현재 구조를 기록합니다. 이후 호환되지 않는 구조 변경이 발생하면 항목이 SEGMENT_STRUCTURE_CHANGED로 실패할 수 있습니다.
  • 같은 논리적 세그먼트 대상을 위한 대기 중 액션은 하나만 접수됩니다. 새 requestId를 사용해도 SEGMENT_ACTION_ALREADY_PENDING을 우회할 수 없습니다.
  • 대기열 실행 실패는 성공한 제출 결과를 변경하지 않고 items[].status의 failed와 errorCode로 표시됩니다.
  • begin과 end의 단위는 초입니다. begin은 0 이상이어야 하며 end는 begin보다 커야 합니다. 워커는 밀리초 단위로 반올림하며 최소 0.1초의 길이가 필요합니다.
  • 워커는 최신 상태의 인접 원본 세그먼트와 건너뛴 범위를 확인합니다. 같은 화자의 인접 세그먼트는 겹치거나 경계를 공유할 수 없으며, 번역 시간 건너뛰기 구간과 겹치는 경우에도 거부됩니다.
  • 원본 타이밍과 사용 가능한 대응 번역의 타이밍을 함께 업데이트합니다. 아직 교정을 기다리는 언어 작업은 번역 타이밍 업데이트에서 건너뜁니다.
  • 워커가 발견한 타이밍 오류는 접수 실패 응답이 아니라 실패한 큐 항목으로 보고되며, 대개 ACTION_REJECTED가 사용됩니다.
  • 제출, 취소, 폴링 및 재실행을 포함한 대기열 응답에는 작업 메타데이터만 포함됩니다. 전사 내용은 필수 transcription:read 권한으로 transcripts_get을 사용해 읽으세요.

사용량

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

오류