> ## 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.
# 번역 동영상 또는 오디오 프로젝트 생성
> 업로드한 fileKey로 프로젝트를 만들고, 전사 및 번역한 뒤 음성을 합성합니다. 제공한 SRT, 음성, 자막, 선택적 립싱크를 지원합니다. 일반 미디어 크레딧을 사용합니다. 선택적 webhookUrl로 처리 이벤트를 받을 수 있습니다. projects_status를 조회하세요.
업로드한 fileKey로 프로젝트를 만들고, 전사 및 번역한 뒤 음성을 합성합니다. 제공한 SRT, 음성, 자막, 선택적 립싱크를 지원합니다. 일반 미디어 크레딧을 사용합니다. 선택적 webhookUrl로 처리 이벤트를 받을 수 있습니다. projects\_status를 조회하세요.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/translations_create
```
## 인증 및 권한
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이
REST 엔드포인트에서는 사용할 수 없습니다.
필요한 권한: `projects:write`, `translations:write`, `transcription:write`.
활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.
## 매개변수
텍스트 값입니다.
최소 길이: 1. 최대 길이: 1024.
텍스트 값입니다.
허용값: "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".
텍스트 값입니다.
허용값: "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".
텍스트 값입니다.
최소 길이: 1. 최대 길이: 200.
텍스트 값입니다.
허용값: "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".
값 목록입니다. 항목 구조는 전체 입력 스키마를 참고하세요.
최대 항목 수: 1000.
불리언 값입니다.
텍스트 값입니다.
최대 길이: 1000000.
텍스트 값입니다.
최대 길이: 2048. 형식: "uri".
전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 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. 최댓값: 70.
텍스트 값입니다.
허용값: "cloning", "custom".
텍스트 값입니다.
최소 길이: 1. 최대 길이: 128.
불리언 값입니다.
텍스트 값입니다.
허용값: "translated", "original".
텍스트 값입니다.
허용값: "studio", "realistic".
텍스트 값입니다.
허용값: "standard", "pro", "studio".
불리언 값입니다.
JSON 객체입니다. 중첩 필드는 전체 입력 스키마를 참고하세요.
값 목록입니다. 항목 구조는 전체 입력 스키마를 참고하세요.
최대 항목 수: 100.
텍스트 값입니다.
최대 길이: 1000000.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.
```json theme={null}
{
"type": "object",
"properties": {
"fileKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"targetLanguage": {
"type": "string",
"enum": [
"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"
]
},
"originalLanguage": {
"type": "string",
"enum": [
"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"
]
},
"projectName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"numberOfSpeakers": {
"type": "string",
"enum": [
"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"
]
},
"brandVocabulary": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"removeFillerWords": {
"type": "boolean"
},
"sourceSrt": {
"type": "string",
"maxLength": 1000000
},
"webhookUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"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."
},
"keepBackgroundMusic": {
"type": "boolean"
},
"keepOriginalVoice": {
"type": "boolean"
},
"originalVoiceVolume": {
"type": "number",
"minimum": 1,
"maximum": 70
},
"voiceMode": {
"type": "string",
"enum": ["cloning", "custom"]
},
"voiceId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"subtitles": {
"type": "boolean"
},
"subtitlesSource": {
"type": "string",
"enum": ["translated", "original"]
},
"voiceIsolatorOption": {
"type": "string",
"enum": ["studio", "realistic"]
},
"lipSyncMode": {
"type": "string",
"enum": ["standard", "pro", "studio"]
},
"activeSpeakerDetectionEnabled": {
"type": "boolean"
},
"voiceCloningSettings": {
"type": "object",
"properties": {
"stability": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"similarity": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": ["stability", "similarity"],
"additionalProperties": false
},
"translationTimeSkips": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"startTime": {
"type": "number",
"minimum": 0
},
"endTime": {
"type": "number",
"exclusiveMinimum": 0
}
},
"required": ["startTime", "endTime"],
"additionalProperties": false
}
},
"translatedSrt": {
"type": "string",
"maxLength": 1000000
}
},
"required": ["fileKey", "targetLanguage"],
"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/translations_create' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"fileKey":"uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4","targetLanguage":"english","originalLanguage":"fr","projectName":"Product launch","numberOfSpeakers":"auto-detect","brandVocabulary":["VoiceCheap"],"removeFillerWords":true,"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","keepBackgroundMusic":true,"keepOriginalVoice":false,"voiceMode":"cloning","subtitles":true,"subtitlesSource":"translated","voiceIsolatorOption":"studio"}'
```
```javascript JavaScript theme={null}
const input = {
fileKey: 'uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4',
targetLanguage: 'english',
originalLanguage: 'fr',
projectName: 'Product launch',
numberOfSpeakers: 'auto-detect',
brandVocabulary: ['VoiceCheap'],
removeFillerWords: true,
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
keepBackgroundMusic: true,
keepOriginalVoice: false,
voiceMode: 'cloning',
subtitles: true,
subtitlesSource: 'translated',
voiceIsolatorOption: 'studio',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_create', {
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/translations_create",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"fileKey": "uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4", "targetLanguage": "english", "originalLanguage": "fr", "projectName": "Product launch", "numberOfSpeakers": "auto-detect", "brandVocabulary": ["VoiceCheap"], "removeFillerWords": True, "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "keepBackgroundMusic": True, "keepOriginalVoice": False, "voiceMode": "cloning", "subtitles": True, "subtitlesSource": "translated", "voiceIsolatorOption": "studio"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## 응답
성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다.
전사 후 번역 및 음성 생성, 또는 제공된 번역의 더빙을 시작한 뒤 새 프로젝트 식별자를 반환합니다.
```json HTTP 200 theme={null}
{
"data": {
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "project_launch_2026",
"estimatedDuration": 10
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
## 결과 필드
| 필드 | 설명 |
| - | - |
| `data.success` | 백그라운드 워크플로가 접수되었으면 true입니다. 미디어가 완성되었음을 나타내지는 않습니다. |
| `data.message` | 번역 또는 제공된 번역을 사용한 더빙의 확인 응답입니다. |
| `data.projectId` | 상위 프로젝트 식별자입니다. |
| `data.estimatedDuration` | 대략적인 분 단위 처리 예상 시간: ceil(초 단위 원본 길이 / 60) \* 5. |
## translatedSrt가 전달되었으며 허용되었습니다.
동일한 결과 필드로 전달된 대상 텍스트의 더빙 접수를 확인합니다.
```json HTTP 200 theme={null}
{
"data": {
"success": true,
"message": "Dubbing started successfully from the provided translation. Use the status endpoint to track progress.",
"projectId": "project_launch_2026",
"estimatedDuration": 10
}
}
```
## 이 요청 복구 및 폴링
연결이 끊어진 후에도 동일한 식별자를 사용하세요. 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":"41321bda-e243-4b6f-96a4-622cd047c991","operation":"translations_create"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_create",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "project_launch_2026",
"estimatedDuration": 10
}
}
}
```
## 작업 참고 사항
* 완료된 fileKey는 인증된 요청 주체의 소유여야 합니다. 서버가 저장된 미디어의 길이와 크기를 측정합니다.
* 선택적 sourceSrt를 제공하려면 originalLanguage를 명시해야 합니다. translatedSrt도 제공하는 경우 두 SRT의 자막 구간 수가 같아야 합니다. 제공된 번역은 자막 구간 인덱스에 따라 짝지어집니다.
* translatedSrt를 제공하면 워크플로가 해당 텍스트를 더빙하고 전달된 번역의 접수 확인을 반환합니다. sourceSrt가 있으면 인덱스로 큐를 정렬하며, sourceSrt가 없으면 자동 전사문 타임라인을 사용합니다.
* 생성 결과에는 workId나 translatedVersionId가 없습니다. 해당 값이 생성되면 projects\_status 또는 projects\_get에서 가져오세요.
* voiceMode의 기본값은 cloning입니다. voiceMode custom에서는 카탈로그 음성이나 인증된 계정이 저장한 사용자 지정 음성을 사용하고 voiceCloningSettings를 지정하지 마세요. 팀 결제를 사용해도 다른 구성원이 저장한 음성에 접근할 수 없습니다.
* 선택적인 subtitles, lipSyncMode 및 translationTimeSkips에는 비디오 입력이 필요합니다. 건너뛴 구간은 미디어 길이 내에 있어야 하며 keepBackgroundMusic은 true, keepOriginalVoice는 false여야 합니다.
* lipSyncMode는 요금제 및 일반 미디어 크레딧 확인 조건에 따라 standard, pro 또는 studio를 허용합니다. 월간 API 호출이 무제한이어도 음성과 립싱크가 무료가 되는 것은 아닙니다.
* 미디어 워크플로는 projects\_status를 폴링하고, 모든 언어 버전은 projects\_get으로 가져오세요.
* originalLanguage는 fr 또는 en과 같은 원본 언어 코드(허용되는 경우 auto-detect)를 사용하고, targetLanguage는 english와 같은 지원 대상 언어 이름을 사용합니다.
## 사용량
성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.
## 오류
| HTTP 상태 | 코드 | 의미 또는 복구 방법 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | 자격 증명이 access\_token 또는 api\_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요. |
| 400 | `FILE_TOO_LARGE` | 저장된 업로드가 계정의 업로드 크기 한도를 초과합니다. |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key 헤더와 본문의 requestId 필드가 일치해야 합니다. |
| 400 | `INVALID_FILE_TYPE` | 업로드한 파일명에 지원되는 오디오 또는 동영상 확장자가 없습니다. |
| 400 | `INVALID_MEDIA_DURATION` | 측정된 길이가 유효하지 않거나 플랜 한도를 초과합니다. |
| 400 | `INVALID_REQUEST_ID` | UUID v4인 requestId 또는 Idempotency-Key를 제공하세요. |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt에는 유효한 SRT 큐가 포함되어야 합니다. |
| 400 | `INVALID_TRANSLATED_SRT` | 제공된 대상 언어 SRT의 형식이 잘못되었습니다. |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | 립싱크에는 동영상 입력이 필요합니다. |
| 400 | `LIPSYNC_VIDEO_TOO_LONG` | 동영상이 선택한 립싱크 모드의 길이 제한을 초과합니다. |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt를 제공할 때는 originalLanguage를 명시적으로 설정하세요. |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | 영상에 입힌 자막을 만들려면 동영상 입력이 필요합니다. |
| 400 | `TRANSLATED_SRT_CUE_COUNT_MISMATCH` | sourceSrt와 translatedSrt를 함께 전달하면 각각 같은 수의 큐를 포함해야 합니다. |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | 번역 시간 건너뛰기는 keepOriginalVoice가 true인 경우와 함께 사용할 수 없습니다. |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | 번역 시간 구간을 건너뛰려면 동영상 입력이 필요합니다. |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | 건너뛴 구간이 미디어 길이를 벗어납니다. |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | 번역 시간 구간을 건너뛰려면 keepBackgroundMusic이 true여야 합니다. |
| 400 | `VALIDATION_ERROR` | 스키마에 따라 입력을 수정하세요. 유효하지 않거나 일관되지 않은 값은 실행 전에 거부됩니다. |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | voiceCloningSettings는 voiceMode가 cloning일 때만 적용됩니다. |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId는 voiceMode cloning과 함께 사용할 수 없습니다. |
| 400 | `VOICE_ID_REQUIRED` | voiceMode가 custom이면 voiceId가 필요합니다. |
| 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 | `CUSTOM_VOICE_ACCESS_DENIED` | 선택한 음성은 카탈로그 음성도 아니고 인증된 계정이 저장한 사용자 지정 음성도 아닙니다. |
| 403 | `INSUFFICIENT_CREDITS` | 선택한 음성 및 선택적 립싱크 설정에 필요한 미디어 크레딧이 계정에 부족합니다. |
| 403 | `INSUFFICIENT_SCOPE` | 필요한 모든 권한을 부여하거나 다른 자격 증명을 사용하세요. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | 계정의 통합 한도를 확인할 수 없습니다. |
| 403 | `INVALID_FILE_REFERENCE` | fileKey는 인증된 작업 수행자에게 속한 완료된 업로드를 식별해야 합니다. |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | 선택한 추가 립싱크 모드는 현재 요금제에서 사용할 수 없습니다. |
| 403 | `SUBSCRIPTION_REQUIRED` | 활성 유료 구독을 사용하세요. |
| 403 | `TEAM_OWNER_NOT_FOUND` | 실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다. |
| 404 | `MEDIA_NOT_FOUND` | 업로드된 객체가 없거나 비어 있습니다. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | 이 계정에서는 이미 10개의 연동 액션이 실행 중입니다. 새 액션을 시작하기 전에 기존 요청을 폴링하세요. |
| 409 | `IDEMPOTENCY_CONFLICT` | 동일한 작업과 인수에 대해서만 식별자를 재사용하세요. |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | 계정이 이미 최대 동시 API 번역 수에 도달했습니다. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 월간 한도가 초기화될 때까지 기다리거나 요금제를 변경하세요. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After가 있으면 지정된 시간만큼 기다리고 백오프를 적용하세요. |
| 500 | `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": ["projects:write", "translations:write", "transcription:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.