> ## 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.
# 번역 시작
> 비디오 또는 오디오 파일을 업로드하고 새로운 번역 프로젝트를 시작하세요
# 번역 시작
비디오 또는 오디오 파일을 업로드하여 새로운 번역 프로젝트를 생성하세요. 번역 프로세스는 백그라운드에서 비동기적으로 실행됩니다. 진행 상황을 추적하고 결과를 검색하려면 [상태 엔드포인트](/docs/ko/api-reference/translation-status)을 사용하세요. 번역된 버전 기록이나 립싱크 기록이 필요할 때는 [프로젝트 세부 정보 가져오기](/docs/ko/api-reference/project-details)을 사용하세요.
## 동시성 제한
계정당 최대 10개의 번역을 동시에 실행할 수 있습니다. 이미 10개의 번역이 진행 중인 경우, 새로운 요청은 `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429)을 반환합니다.
## 요청
이 엔드포인트는 파일 업로드와 함께 `multipart/form-data`을 허용합니다.
### 헤더
귀하의 VoiceCheap API 키입니다. [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api)에서 키를 발급받으세요.
### 본문 매개변수
번역할 비디오 또는 오디오 파일입니다.
**지원되는 비디오 형식:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg`
**지원되는 오디오 형식:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`
**플랜별 최대 파일 크기:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB, Enterprise 60 GB.
콘텐츠를 번역할 언어입니다. 소문자로 입력해야 합니다.
**허용되는 값 (70개 이상):** `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`, `punjabi`, `romanian`, `russian`, `serbian`, `slovak`, `slovenian`, `spanish`, `swahili`, `swedish`, `tagalog`, `tamil`, `telugu`, `thai`, `turkish`, `ukrainian`, `urdu`, `vietnamese`, `welsh`, `yoruba`, `zulu`
ISO 언어 코드를 사용하는 콘텐츠의 원본 언어입니다 (예: `en`, `es`, `fr`, `de`, `ja`, `zh`).
**강력 권장: 자동 감지를 위해 이 항목을 비워 두세요.**
언어 코드가 정확하고 유효한 ISO 형식임을 100% 확신하는 경우에만 이 매개변수를 제공하세요. 잘못된 언어 코드는 전사 실패를 유발합니다. 당사의 자동 감지는 80개 이상의 언어를 지원하며 매우 정확합니다.
**기본값:** `auto-detect`
프로젝트의 사용자 지정 이름입니다. 대시보드에서 프로젝트를 식별하는 데 유용합니다.
**기본값:** 제공되지 않으면 프로젝트 ID가 사용됩니다.
이 프로젝트에 대한 [웹훅 이벤트](/docs/ko/api-reference/webhooks)을 수신하는 https 엔드포인트이며,
계정에 구성된 엔드포인트를 재정의합니다.
**기본값:** 구성된 경우 계정 웹훅 엔드포인트가 사용됩니다.
`auto-detect` 또는 `1`에서 `32` 사이의 정수입니다. 화자 수를 알고 있으면 화자 분리(diarization) 성능이 향상될 수 있습니다.
**기본값:** `auto-detect`
요청별 이름, 브랜드, 약어 또는 전문 용어의 JSON 문자열 배열입니다. 이러한 용어는 저장된 계정 또는 팀 용어집과 병합됩니다.
번역 전 원본 전사에서 일반적인 추임새 단어를 제거합니다.
**기본값:** `true`
기존 원본 언어 SRT 전사 파일입니다. 이 필드가 제공될 때 `originalLanguage`을 명시해야 합니다.
출력물에서 배경 오디오를 보존할지 여부입니다.
활성화하면 원본 음성만 제거(스템 분리)하면서 배경 음악, 주변 소음, 웃음소리, 박수 소리 및 군중 소리를 유지합니다. 원본에 배경 오디오가 없는 경우 끄십시오.
**기본값:** `true`
번역된 음성 아래에 원본 화자의 목소리를 작게 유지합니다.
**기본값:** `false`
`keepOriginalVoice`가 활성화된 경우 `1`에서 `70`까지의 원본 음성 볼륨입니다.
**기본값:** `30`
`keepBackgroundMusic`이 활성화된 경우의 음성 분리 모드입니다. 음성 분리의 품질과 특성을 제어합니다.
전문적인 오디오 품질을 위해 설계된 기본 음성 처리 방식입니다:
* 에코 및 잔향 제거
* 기술적 결함 정리
* 맑고 선명한 음성 생성
**권장 대상:** 오디오 품질이 가장 중요한 대부분의 프로젝트. 튜토리얼, 교육 콘텐츠, 마케팅 비디오 및 최적의 음성 선명도가 필요한 모든 콘텐츠에 이상적입니다.
녹음 환경의 자연스러운 특성을 보존합니다:
* 원본 녹음과 더 가까운 사운드 유지
* 환경적 특성 보존
**권장 대상:** 야외 브이로그, 다큐멘터리 또는 사운드 분위기가 경험의 필수적인 부분인 콘텐츠와 같이 환경의 진정성이 중요한 콘텐츠.
이 옵션은 배경 요소를 보존하기 때문에 경우에 따라 아티팩트나 예상치 못한 효과가 발생할 수 있습니다.
**허용되는 값:** `studio`, `realistic`
**기본값:** `studio`
번역된 비디오에 자막을 생성할지 여부입니다.
활성화하면 깔끔한 넷플릭스 스타일의 흑백 자막이 추가됩니다. `subtitlesSource`을 사용하여 원본(원본 언어) 또는 번역된(대상 언어) 텍스트를 선택하세요. 자막은 최적의 가독성을 위해 자동으로 동기화됩니다.
**참고:** 번인(Burned-in) 자막을 사용하려면 `subtitles` 필터(libass)가 포함된 FFmpeg이 필요합니다. 사용할 수 없는 경우 API는 하드 번인 스타일 대신 자막 트랙을 삽입하는 방식으로 대체됩니다.
**기본값:** `false`
`subtitles`이 활성화된 경우 자막 텍스트 소스를 선택합니다.
**허용된 값:** `translated`, `original`
**기본값:** `translated`
**참고:** `original`이 선택되었으나 원본 전사가 제공되지 않는 경우, 자막은 `translated`로 대체됩니다.
번역 완료 후 립싱크 처리를 트리거합니다.
* `standard` = Lip Sync
* `pro` = Lip Sync Pro
* `studio` = Lip Sync Studio
프리미엄 모드는 일반적인 플랜, 기간 및 크레딧 요구 사항을 적용합니다.
**기본값:** 립싱크를 건너뛰려면 필드를 생략하십시오.
요청된 립싱크 실행에 대해 활성 화자 감지를 활성화합니다.
**기본값:** `false`
이전 버전과의 호환성을 위해 유지되는 레거시 립싱크 선택기입니다.
* `false` = 표준 립싱크 (**비디오 1분당 4분 크레딧**)
* `true` = Lip Sync Pro (**비디오 1분당 9분 크레딧**)
Lip Sync Pro은 Creator 플랜부터 사용할 수 있습니다.
**최대 지속 시간:** 비디오당 30분.
**지연 시간:** 립싱크 처리는 일반적으로 원본 비디오 지속 시간의 **2배\~4배**가 추가됩니다.
API로 트리거된 요청에 대해서는 립싱크 완료 및 실패 이메일이 발송되지 않습니다. [상태 엔드포인트](/docs/ko/api-reference/translation-status)을 사용하여
진행 상황을 추적하십시오.
**기본값:** 활성화되지 않음 (립싱크를 건너뛰려면 필드를 생략하십시오)
**Form-data:** 불리언 값을 `true` 또는 `false` 문자열로 보냅니다 (예: `-F "lipsyncPro=false"`).
`lipsyncPro`을 충돌하는 `lipSyncMode`과 결합하지 마십시오.
음성 전략: `cloning` 또는 `custom`.
**기본값:** `cloning`
`voiceMode`이 `custom`일 때 필수입니다. 음성은 유효한 프로젝트 소유자의 것이어야 합니다. 임의의 음성 ID나 소유자가 없는 음성 ID는 거부됩니다.
생성된 음성을 고급 제어하기 위해 음성 복제 매개변수를 미세 조정합니다. form-data 사용 시 JSON 문자열로 전달하십시오. 모든 값은 0에서 1 사이여야 합니다 (0.01 단위).
이 설정은 `voiceMode`이 `cloning`일 때만 적용됩니다.
**음성 안정성 (0.00 - 1.00)**
음성의 안정성과 각 생성 간의 무작위성을 결정합니다.
* **낮은 값**은 더 넓은 감정 범위를 허용하지만 어색하거나 급한 말투를 유발할 수 있습니다
* **높은 값**은 더 일관된 출력을 생성하지만 단조롭게 들릴 수 있습니다
**기본값:** `0.60`
**팁:** 억양 재현을 피하려면 `0.80`을 사용하십시오
**음성 유사도 (0.00 - 1.00)**
AI가 원본 음성을 얼마나 밀접하게 따를지 제어합니다.
* **높은 값**은 복제된 음성을 원본과 더 유사하게 만듭니다
* 원본 오디오에 노이즈가 많고 유사도가 너무 높으면 아티팩트나 배경 소음이 생성된 음성에 포함될 수 있습니다
**기본값:** `0.85`
**팁:** 억양 재현을 피하려면 `0.20`을 사용하십시오
**화자 부스트 (0.00 - 1.00)**
원본 화자와의 유사도를 높입니다. 이는 원본 음성과의 닮은 점을 증가시키는 미세한 향상 기능입니다.
**참고:** 높은 값은 계산 시간과 지연 시간을 증가시킵니다.
**기본값:** `0.60`
**팁:** 억양 재현을 피하려면 `0.00`을 사용하십시오
**기본값 (균형 잡힘):**
```json theme={null}
{
"stability": 0.6,
"similarity": 0.85,
"speakerBoost": 0.6
}
```
**억양 재현 방지를 위해 권장됨:**
```json theme={null}
{
"stability": 0.8,
"similarity": 0.2,
"speakerBoost": 0.0
}
```
원본 언어로 유지되어야 하는 소스 시간 범위의 JSON 배열입니다.
```json theme={null}
[
{ "startTime": 10.2, "endTime": 12.8 }
]
```
시간 건너뛰기에는 비디오 입력과 `keepBackgroundMusic=true`이 필요합니다. 이는 `keepOriginalVoice`과 결합할 수 없으며 전사 세그먼트와 겹칠 수 없습니다.
## 응답
성공적인 요청의 경우 항상 `true`
결과를 설명하는 사람이 읽을 수 있는 메시지
생성된 더빙 프로젝트의 고유 식별자입니다. 이 ID를 사용하여 상태를 확인하세요.
분 단위의 대략적인 처리 예상 시간입니다. 현재 예상 처리 시간은 소스 미디어 1분당 5분입니다.
## 예시
유효한 계정 또는 팀의 저장된 용어집 규칙 및 맞춤 더빙 지침이 자동으로 적용됩니다.
```bash cURL theme={null}
curl -X POST https://api.voicecheap.ai/v1/translate \
-H "x-api-key: vc_your-api-key" \
-F "file=@video.mp4" \
-F "targetLanguage=spanish" \
-F "projectName=My Spanish Translation" \
-F "numberOfSpeakers=2" \
-F 'brandVocabulary=["VoiceCheap","SmartSync"]' \
-F "removeFillerWords=true" \
-F "keepBackgroundMusic=true" \
-F "keepOriginalVoice=false" \
-F "voiceIsolatorOption=studio" \
-F "subtitles=true" \
-F "subtitlesSource=translated" \
-F "lipSyncMode=standard" \
-F "activeSpeakerDetectionEnabled=true"
```
```typescript TypeScript theme={null}
interface StartTranslationResponse {
success: boolean;
message: string;
projectId: string;
estimatedDuration: number;
}
interface VoiceCloningSettings {
stability: number; // 0.00 - 1.00
similarity: number; // 0.00 - 1.00
speakerBoost: number; // 0.00 - 1.00
}
interface StartTranslationRequest {
targetLanguage: string;
originalLanguage?: string;
projectName?: string;
numberOfSpeakers?: 'auto-detect' | string;
brandVocabulary?: string[];
removeFillerWords?: boolean;
keepBackgroundMusic?: boolean;
keepOriginalVoice?: boolean;
originalVoiceVolume?: number;
voiceMode?: 'cloning' | 'custom';
voiceId?: string;
voiceIsolatorOption?: 'studio' | 'realistic';
subtitles?: boolean;
subtitlesSource?: 'translated' | 'original';
lipSyncMode?: 'standard' | 'pro' | 'studio';
activeSpeakerDetectionEnabled?: boolean;
voiceCloningSettings?: VoiceCloningSettings;
translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
}
async function startTranslation(
file: File,
targetLanguage: string,
options?: {
originalLanguage?: string;
projectName?: string;
numberOfSpeakers?: 'auto-detect' | string;
brandVocabulary?: string[];
removeFillerWords?: boolean;
keepBackgroundMusic?: boolean;
keepOriginalVoice?: boolean;
originalVoiceVolume?: number;
voiceMode?: 'cloning' | 'custom';
voiceId?: string;
voiceIsolatorOption?: 'studio' | 'realistic';
subtitles?: boolean;
subtitlesSource?: 'translated' | 'original';
lipSyncMode?: 'standard' | 'pro' | 'studio';
activeSpeakerDetectionEnabled?: boolean;
voiceCloningSettings?: VoiceCloningSettings;
translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
},
): Promise {
const formData = new FormData();
formData.append('file', file);
formData.append('targetLanguage', targetLanguage);
if (options?.projectName) {
formData.append('projectName', options.projectName);
}
if (options?.originalLanguage) {
formData.append('originalLanguage', options.originalLanguage);
}
if (options?.numberOfSpeakers) {
formData.append('numberOfSpeakers', options.numberOfSpeakers);
}
if (options?.brandVocabulary) {
formData.append('brandVocabulary', JSON.stringify(options.brandVocabulary));
}
if (options?.removeFillerWords !== undefined) {
formData.append('removeFillerWords', String(options.removeFillerWords));
}
if (options?.keepBackgroundMusic !== undefined) {
formData.append('keepBackgroundMusic', String(options.keepBackgroundMusic));
}
if (options?.keepOriginalVoice !== undefined) {
formData.append('keepOriginalVoice', String(options.keepOriginalVoice));
}
if (options?.originalVoiceVolume !== undefined) {
formData.append('originalVoiceVolume', String(options.originalVoiceVolume));
}
if (options?.voiceMode) {
formData.append('voiceMode', options.voiceMode);
}
if (options?.voiceId) {
formData.append('voiceId', options.voiceId);
}
if (options?.voiceIsolatorOption) {
formData.append('voiceIsolatorOption', options.voiceIsolatorOption);
}
if (options?.subtitles !== undefined) {
formData.append('subtitles', String(options.subtitles));
}
if (options?.subtitlesSource) {
formData.append('subtitlesSource', options.subtitlesSource);
}
if (options?.lipSyncMode) {
formData.append('lipSyncMode', options.lipSyncMode);
}
if (options?.activeSpeakerDetectionEnabled !== undefined) {
formData.append('activeSpeakerDetectionEnabled', String(options.activeSpeakerDetectionEnabled));
}
if (options?.voiceCloningSettings) {
formData.append('voiceCloningSettings', JSON.stringify(options.voiceCloningSettings));
}
if (options?.translationTimeSkips) {
formData.append('translationTimeSkips', JSON.stringify(options.translationTimeSkips));
}
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: {
'x-api-key': 'vc_your-api-key',
},
body: formData,
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || 'Translation failed');
}
return response.json();
}
// Usage example
const file = document.querySelector('#fileInput')?.files?.[0];
if (file) {
const result = await startTranslation(file, 'spanish', {
projectName: 'My Spanish Translation',
keepBackgroundMusic: true,
voiceIsolatorOption: 'studio',
subtitles: true,
subtitlesSource: 'translated',
voiceCloningSettings: {
stability: 0.6,
similarity: 0.85,
speakerBoost: 0.6,
},
});
console.log('Project ID:', result.projectId);
}
```
```javascript JavaScript theme={null}
const formData = new FormData();
formData.append('file', videoFile);
formData.append('targetLanguage', 'spanish');
formData.append('projectName', 'My Spanish Translation');
formData.append('keepBackgroundMusic', 'true');
formData.append('voiceIsolatorOption', 'studio');
formData.append('subtitles', 'true');
formData.append('subtitlesSource', 'translated');
formData.append(
'voiceCloningSettings',
JSON.stringify({
stability: 0.6,
similarity: 0.85,
speakerBoost: 0.6,
}),
);
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: {
'x-api-key': 'vc_your-api-key',
},
body: formData,
});
const data = await response.json();
console.log('Project ID:', data.projectId);
```
```python Python theme={null}
import requests
import json
files = {'file': open('video.mp4', 'rb')}
data = {
'targetLanguage': 'spanish',
'projectName': 'My Spanish Translation',
'keepBackgroundMusic': 'true',
'voiceIsolatorOption': 'studio',
'subtitles': 'true',
'subtitlesSource': 'translated',
'voiceCloningSettings': json.dumps({
'stability': 0.60,
'similarity': 0.85,
'speakerBoost': 0.60
})
}
headers = {'x-api-key': 'vc_your-api-key'}
response = requests.post(
'https://api.voicecheap.ai/v1/translate',
headers=headers,
files=files,
data=data
)
result = response.json()
print(f"Project ID: {result['projectId']}")
```
```php PHP theme={null}
0.60,
'similarity' => 0.85,
'speakerBoost' => 0.60
]);
$postFields = [
'file' => new CURLFile('video.mp4'),
'targetLanguage' => 'spanish',
'projectName' => 'My Spanish Translation',
'keepBackgroundMusic' => 'true',
'voiceIsolatorOption' => 'studio',
'subtitles' => 'true',
'subtitlesSource' => 'translated',
'voiceCloningSettings' => $voiceCloningSettings
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.voicecheap.ai/v1/translate',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postFields,
CURLOPT_HTTPHEADER => [
'x-api-key: vc_your-api-key'
]
]);
$response = curl_exec($curl);
$result = json_decode($response, true);
echo "Project ID: " . $result['projectId'];
```
## 응답 예시
```json theme={null}
{
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "abc123-def456-ghi789",
"estimatedDuration": 15
}
```
## 오류
| 상태 | 코드 | 설명 |
| --- | ----------------------------------------------- | ------------------------------------------ |
| 400 | `FILE_REQUIRED` | 요청과 함께 업로드된 파일이 없습니다 |
| 400 | `INVALID_FILE_TYPE` | 업로드된 파일 형식은 지원되지 않습니다 |
| 400 | `DURATION_DETECTION_FAILED` | 업로드된 파일의 길이를 감지할 수 없습니다 |
| 400 | `INVALID_MULTIPART_REQUEST` | 멀티파트 폼 데이터가 잘못되었거나 필드 제한을 초과했습니다 |
| 400 | `INVALID_BOOLEAN_VALUE` | 부울 매개변수의 값이 잘못되었습니다 ("true" 또는 "false" 사용) |
| 400 | `INVALID_JSON_FORMAT` | voiceCloningSettings JSON이 잘못되었습니다 |
| 400 | `INVALID_BRAND_VOCABULARY` | 요청별 어휘 항목이 유효하지 않습니다 |
| 400 | `INVALID_SOURCE_SRT` | 제공된 소스 SRT가 잘못되었습니다 |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt에는 명시적인 originalLanguage가 필요합니다 |
| 400 | `VOICE_ID_REQUIRED` | 음성 ID 없이 맞춤 음성 모드가 선택되었습니다 |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | 음성 ID가 음성 복제와 결합되었습니다 |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | 복제 설정이 맞춤 음성 모드와 결합되었습니다 |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode가 이전 버전의 lipsyncPro와 충돌합니다 |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | 시간 건너뛰기가 다른 오디오 옵션과 충돌합니다 |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | 시간 건너뛰기에는 배경 오디오가 필요합니다 |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | 시간 건너뛰기가 미디어 길이를 초과합니다 |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | 시간 건너뛰기가 전사 세그먼트와 겹칩니다 |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | 오디오 입력에 대해 하드코딩된 자막이 요청되었습니다 |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | 오디오 입력에 대해 립싱크가 요청되었습니다 |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | 오디오 입력에 대해 시간 건너뛰기가 요청되었습니다 |
| 400 | `LIPSYNC_VIDEO_TOO_LONG` | 지원되는 길이보다 긴 미디어에 대해 립싱크가 요청되었습니다 |
| 413 | `FILE_TOO_LARGE` | 업로드된 파일이 사용자의 플랜 제한을 초과합니다 |
| 401 | `MISSING_API_KEY` | API 키가 필요합니다 |
| 401 | `INVALID_API_KEY_FORMAT` | API 키는 `vc_`으로 시작해야 합니다 |
| 401 | `INVALID_API_KEY` | 제공된 API 키가 유효하지 않습니다 |
| 403 | `API_ACCESS_REQUIRED` | 이 계정에는 API 액세스가 필요합니다 |
| 403 | `SUBSCRIPTION_REQUIRED` | API 액세스에는 유료 구독이 필요합니다 |
| 403 | `INSUFFICIENT_CREDITS` | 이 파일을 처리할 크레딧이 부족합니다 |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | 맞춤 음성이 유효한 프로젝트 소유자의 소유가 아닙니다 |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | 프리미엄 립싱크 모드는 현재 플랜에서 사용할 수 없습니다 |
| 429 | `RATE_LIMIT_EXCEEDED` | 요청이 너무 많습니다 (제한: 분당 10회 요청) |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | 진행 중인 더빙 작업이 너무 많습니다 (제한: 동시 더빙 10개) |