Skip to main content
POST
업로드한 fileKey로 프로젝트를 만들고 전사합니다. 저장된 미디어에서 길이와 파일 크기를 확인합니다. 선택적 webhookUrl로 처리 이벤트를 받을 수 있습니다. projects_status를 조회하세요.

​
인증 및 권한

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

​
매개변수

​
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 1024.
​
string
필수
텍스트 값입니다.허용값: “afrikaans”, “albanian”, “amharic”, “arabic”, “armenian”, “assamese”, “azerbaijani”, “basque”, “belarusian”, “bengali”, “bosnian”, “bulgarian”, “catalan”, “croatian”, “czech”, “danish”, “dutch”, “english”, “british english”, “estonian”, “finnish”, “french”, “french canadian”, “galician”, “german”, “greek”, “gujarati”, “hebrew”, “hindi”, “hungarian”, “icelandic”, “indonesian”, “irish”, “italian”, “japanese”, “kannada”, “kazakh”, “khmer”, “korean”, “lao”, “latvian”, “lithuanian”, “macedonian”, “malay”, “malayalam”, “mandarin”, “marathi”, “mongolian”, “nepali”, “norwegian”, “persian”, “polish”, “portuguese”, “brazilian portuguese”, “pt_brazil”, “punjabi”, “romanian”, “russian”, “serbian”, “slovak”, “slovenian”, “spanish”, “swahili”, “swedish”, “tagalog”, “tamil”, “telugu”, “thai”, “turkish”, “ukrainian”, “urdu”, “vietnamese”, “welsh”, “yoruba”, “zulu”.
​
string
텍스트 값입니다.허용값: “af”, “sq”, “am”, “ar”, “hy”, “as”, “ast”, “az”, “ba”, “eu”, “be”, “bn”, “bs”, “br”, “bg”, “my”, “ca”, “ceb”, “zh”, “hr”, “cs”, “da”, “nl”, “en”, “eo”, “at”, “et”, “fil”, “fo”, “fi”, “fr”, “fr-CA”, “fy”, “ff”, “gd”, “gl”, “lg”, “ka”, “de”, “el”, “gu”, “ht”, “ha”, “haw”, “he”, “hi”, “hu”, “is”, “ig”, “ilo”, “id”, “ia”, “ga”, “it”, “ja”, “jv”, “kea”, “kn”, “kk”, “km”, “kur”, “kir”, “ko”, “lo”, “la”, “luo”, “lv”, “lb”, “ln”, “lt”, “mk”, “mg”, “ms”, “ml”, “mt”, “mi”, “mr”, “mo”, “mn”, “ne”, “no”, “nn”, “nso”, “nya”, “oc”, “or”, “pa”, “ps”, “fa”, “pl”, “pt”, “ro”, “ru”, “sa”, “sr”, “sn”, “sd”, “si”, “sk”, “sl”, “so”, “es”, “su”, “sw”, “ss”, “sv”, “tl”, “tg”, “ta”, “tt”, “te”, “th”, “bo”, “tn”, “tr”, “tk”, “ug”, “uk”, “umb”, “ur”, “uz”, “vi”, “cy”, “wo”, “xh”, “yi”, “yo”, “zu”, “cmn”, “yue”, “en-GB”, “en-US”, “en-AU”, “auto-detect”.
​
string
텍스트 값입니다.최소 길이: 1. 최대 길이: 200.
​
string
텍스트 값입니다.허용값: “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, “9”, “10”, “11”, “12”, “13”, “14”, “15”, “16”, “17”, “18”, “19”, “20”, “21”, “22”, “23”, “24”, “25”, “26”, “27”, “28”, “29”, “30”, “31”, “32”, “auto-detect”.
​
array
값 목록입니다. 항목 구조는 전체 입력 스키마를 참고하세요.최대 항목 수: 1000.
​
boolean
불리언 값입니다.
​
string
텍스트 값입니다.최대 길이: 1000000.
​
string
텍스트 값입니다.최대 길이: 2048. 형식: “uri”.
​
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}$.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

​
멱등성

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

​
요청 예제

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

​
응답

성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다. 전사를 시작한 직후 새 프로젝트 식별 정보를 반환합니다. 번역을 시작하거나 완료된 전사문을 반환하지 않습니다.

​
결과 필드

​
이 요청 복구 및 폴링

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

​
작업 참고 사항

  • 먼저 미디어를 업로드하거나 가져온 다음 인증된 실행 주체가 소유한 완료된 fileKey를 전달하세요. 길이, MIME 유형 및 바이트 크기는 저장된 객체에서 측정됩니다. 호출자가 제어하는 입력 필드가 아닙니다.
  • 이 액션은 전사만 수행하지만 targetLanguage가 필요합니다. 원본 전사가 완료된 후 translations_start 또는 translations_dub을 사용하세요.
  • sourceSrt는 원본 전사 텍스트를 대체하며 originalLanguage를 명시적으로 지정해야 합니다. brandVocabulary는 검증되며, 제공하지 않으면 계정에 저장된 어휘를 사용합니다.
  • webhookUrl은 공개 HTTPS 콜백을 재정의하는 선택적 값입니다. 사설 또는 안전하지 않은 네트워크 대상은 거부됩니다.
  • projects_status를 폴링한 다음 transcripts_get으로 전사문을 가져오세요. 이 결과의 status 값인 processing은 미디어 워크플로를 나타냅니다.
  • originalLanguage는 fr 또는 en과 같은 원본 언어 코드(허용되는 경우 auto-detect)를 사용하고, targetLanguage는 english와 같은 지원 대상 언어 이름을 사용합니다.

​
사용량

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

​
오류