curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","requestId":"41321bda-e243-4b6f-96a4-622cd047c991","changes":{"projectName":"Product launch — English","translationInstructions":"Keep product names unchanged.","keepBackgroundMusic":true,"subtitles":{"isEnable":true,"source":"translated"}}}'
const input = {
projectId: 'project_launch_2026',
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
changes: {
projectName: 'Product launch — English',
translationInstructions: 'Keep product names unchanged.',
keepBackgroundMusic: true,
subtitles: {
isEnable: true,
source: 'translated',
},
},
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_update', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/projects_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "changes": {"projectName": "Product launch — English", "translationInstructions": "Keep product names unchanged.", "keepBackgroundMusic": True, "subtitles": {"isEnable": True, "source": "translated"}}},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"projectId": "project_launch_2026",
"projectName": "Product launch — English",
"status": "success",
"workflow": "translation",
"originalVideoUrl": "https://media.example.com/launch/original.mp4",
"originalLanguage": "fr",
"targetLanguages": [
"english"
],
"duration": 75,
"createdAt": 1792152000000,
"progress": {
"step": "done",
"transcriptionProgress": 100,
"transcriptionStatus": "success"
},
"translations": [
{
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"translatedVersionId": "0fa684f3-4997-4d7a-9424-16d1f9ac849c",
"targetLanguage": "english",
"status": "completed",
"currentStep": "done",
"progress": 100,
"createdAt": 1792152060000,
"completedAt": 1792152300000,
"translatedVideoUrl": "https://media.example.com/launch/english.mp4",
"translatedAudioUrl": "https://media.example.com/launch/english.mp3",
"settings": {
"voiceCloning": true,
"uploadType": "video",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"subtitles": {
"isEnable": false,
"source": "translated"
},
"smartSync": true,
"dubbingMode": "translate",
"voiceIsolatorOption": "studio"
}
}
],
"segmentStructureRevision": 3,
"numberOfSpeakers": 1,
"translationInstructions": "Keep product names unchanged.",
"isReadyForDubbing": true,
"settings": {
"voiceCloning": true,
"customVoice": false,
"customVoiceId": "",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"activeSpeakerDetectionEnabled": false,
"subtitles": {
"isEnable": true,
"source": "translated"
},
"smartSync": true,
"voiceIsolatorOption": "studio",
"voiceCloningSettings": {
"stability": 0.5,
"similarity": 0.75
}
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"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"
}
프로젝트
프로젝트 설정 수정
프로젝트 이름을 변경하거나 번역 지침, 교정 준비 상태, 음성, 배경 오디오 또는 자막 설정을 수정합니다. 명시적인 고객 설정만 변경할 수 있습니다.
POST
/
v1
/
actions
/
projects_update
curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","requestId":"41321bda-e243-4b6f-96a4-622cd047c991","changes":{"projectName":"Product launch — English","translationInstructions":"Keep product names unchanged.","keepBackgroundMusic":true,"subtitles":{"isEnable":true,"source":"translated"}}}'
const input = {
projectId: 'project_launch_2026',
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
changes: {
projectName: 'Product launch — English',
translationInstructions: 'Keep product names unchanged.',
keepBackgroundMusic: true,
subtitles: {
isEnable: true,
source: 'translated',
},
},
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_update', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/projects_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "changes": {"projectName": "Product launch — English", "translationInstructions": "Keep product names unchanged.", "keepBackgroundMusic": True, "subtitles": {"isEnable": True, "source": "translated"}}},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"projectId": "project_launch_2026",
"projectName": "Product launch — English",
"status": "success",
"workflow": "translation",
"originalVideoUrl": "https://media.example.com/launch/original.mp4",
"originalLanguage": "fr",
"targetLanguages": [
"english"
],
"duration": 75,
"createdAt": 1792152000000,
"progress": {
"step": "done",
"transcriptionProgress": 100,
"transcriptionStatus": "success"
},
"translations": [
{
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"translatedVersionId": "0fa684f3-4997-4d7a-9424-16d1f9ac849c",
"targetLanguage": "english",
"status": "completed",
"currentStep": "done",
"progress": 100,
"createdAt": 1792152060000,
"completedAt": 1792152300000,
"translatedVideoUrl": "https://media.example.com/launch/english.mp4",
"translatedAudioUrl": "https://media.example.com/launch/english.mp3",
"settings": {
"voiceCloning": true,
"uploadType": "video",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"subtitles": {
"isEnable": false,
"source": "translated"
},
"smartSync": true,
"dubbingMode": "translate",
"voiceIsolatorOption": "studio"
}
}
],
"segmentStructureRevision": 3,
"numberOfSpeakers": 1,
"translationInstructions": "Keep product names unchanged.",
"isReadyForDubbing": true,
"settings": {
"voiceCloning": true,
"customVoice": false,
"customVoiceId": "",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"activeSpeakerDetectionEnabled": false,
"subtitles": {
"isEnable": true,
"source": "translated"
},
"smartSync": true,
"voiceIsolatorOption": "studio",
"voiceCloningSettings": {
"stability": 0.5,
"similarity": 0.75
}
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"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"
}
프로젝트 이름을 변경하거나 번역 지침, 교정 준비 상태, 음성, 배경 오디오 또는 자막 설정을 수정합니다. 명시적인 고객 설정만 변경할 수 있습니다.
필요한 권한:
POST https://api.voicecheap.ai/v1/actions/projects_update
인증 및 권한
string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이
REST 엔드포인트에서는 사용할 수 없습니다.
projects:write.
활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.
매개변수
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴:
^[^/\\]+$.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}$.object
필수
JSON 객체입니다. 중첩 필드는 전체 입력 스키마를 참고하세요.
전체 입력 스키마
전체 입력 스키마
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"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."
},
"changes": {
"type": "object",
"properties": {
"projectName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"translationInstructions": {
"type": "string",
"maxLength": 1000
},
"isReadyForDubbing": {
"type": "boolean"
},
"voiceCloning": {
"type": "boolean"
},
"keepBackgroundMusic": {
"type": "boolean"
},
"keepOriginalVoice": {
"type": "boolean"
},
"originalVoiceVolume": {
"type": "number",
"minimum": 1,
"maximum": 70
},
"activeSpeakerDetectionEnabled": {
"type": "boolean"
},
"smartSync": {
"type": "boolean"
},
"voiceIsolatorOption": {
"type": "string",
"enum": ["studio", "realistic"]
},
"voiceCloningSettings": {
"type": "object",
"properties": {
"stability": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"similarity": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": ["stability", "similarity"],
"additionalProperties": false
},
"subtitles": {
"type": "object",
"properties": {
"isEnable": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": ["original", "translated"]
}
},
"required": ["isEnable", "source"],
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"required": ["projectId", "changes"],
"additionalProperties": false
}
멱등성
각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.요청 예제
예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","requestId":"41321bda-e243-4b6f-96a4-622cd047c991","changes":{"projectName":"Product launch — English","translationInstructions":"Keep product names unchanged.","keepBackgroundMusic":true,"subtitles":{"isEnable":true,"source":"translated"}}}'
const input = {
projectId: 'project_launch_2026',
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
changes: {
projectName: 'Product launch — English',
translationInstructions: 'Keep product names unchanged.',
keepBackgroundMusic: true,
subtitles: {
isEnable: true,
source: 'translated',
},
},
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_update', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/projects_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "changes": {"projectName": "Product launch — English", "translationInstructions": "Keep product names unchanged.", "keepBackgroundMusic": True, "subtitles": {"isEnable": True, "source": "translated"}}},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
응답
성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다. 명시적으로 전달된 고객 설정을 업데이트한 후 새로 조회한 공개 프로젝트 세부 정보를 반환합니다.{
"data": {
"projectId": "project_launch_2026",
"projectName": "Product launch — English",
"status": "success",
"workflow": "translation",
"originalVideoUrl": "https://media.example.com/launch/original.mp4",
"originalLanguage": "fr",
"targetLanguages": [
"english"
],
"duration": 75,
"createdAt": 1792152000000,
"progress": {
"step": "done",
"transcriptionProgress": 100,
"transcriptionStatus": "success"
},
"translations": [
{
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"translatedVersionId": "0fa684f3-4997-4d7a-9424-16d1f9ac849c",
"targetLanguage": "english",
"status": "completed",
"currentStep": "done",
"progress": 100,
"createdAt": 1792152060000,
"completedAt": 1792152300000,
"translatedVideoUrl": "https://media.example.com/launch/english.mp4",
"translatedAudioUrl": "https://media.example.com/launch/english.mp3",
"settings": {
"voiceCloning": true,
"uploadType": "video",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"subtitles": {
"isEnable": false,
"source": "translated"
},
"smartSync": true,
"dubbingMode": "translate",
"voiceIsolatorOption": "studio"
}
}
],
"segmentStructureRevision": 3,
"numberOfSpeakers": 1,
"translationInstructions": "Keep product names unchanged.",
"isReadyForDubbing": true,
"settings": {
"voiceCloning": true,
"customVoice": false,
"customVoiceId": "",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"activeSpeakerDetectionEnabled": false,
"subtitles": {
"isEnable": true,
"source": "translated"
},
"smartSync": true,
"voiceIsolatorOption": "studio",
"voiceCloningSettings": {
"stability": 0.5,
"similarity": 0.75
}
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"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.projectId | 접근 가능한 프로젝트 식별자입니다. |
data.projectName | 고객에게 표시되는 프로젝트 이름입니다. |
data.status | 프로젝트 요약: processing, success 또는 failed입니다. |
data.workflow | 전사 전용 프로젝트는 transcription, 더빙 프로젝트는 translation입니다. |
data.originalVideoUrl | 오디오 프로젝트를 포함한 저장된 원본 미디어 URL입니다. 없으면 빈 문자열입니다. |
data.originalLanguage | 감지되거나 선택된 원본 언어이며, 확인할 수 없으면 unknown입니다. |
data.targetLanguages | 대상 언어 이름의 배열입니다. |
data.duration | 원본 미디어 길이(초 단위)입니다. |
data.createdAt | Unix 밀리초로 표시한 프로젝트 생성 시각입니다. |
data.progress | 공개 전사 단계, 선택적 transcriptionProgress 및 transcriptionStatus입니다. |
data.translations | 모든 언어 작업에 속한 전체 번역 버전이며, 정규화된 createdAt을 기준으로 최신순 정렬됩니다. |
data.segmentStructureRevision | 현재 원문 세그먼트 구조 리비전이며, 기본값은 0입니다. 이 값을 segments_delete 또는 segments_merge의 expectedSegmentStructureRevision으로 전달하세요. |
data.numberOfSpeakers | 저장되어 있는 경우 제공되는 원본 화자 수입니다. |
data.translationInstructions | 현재 프로젝트 번역 지침입니다. 저장된 지침이 없으면 빈 문자열입니다. |
data.isReadyForDubbing | 저장된 프로젝트가 더빙 준비 완료로 표시된 경우에만 true입니다. |
data.settings | 프로젝트 더빙 설정 또는 이전 설정에서 선택한 선택적인 고객 설정입니다. 저장된 필드만 반환되며, 값이 없는 선택 필드는 생략됩니다. |
data.settings.voiceCloning | 선택적인 프로젝트 음성 복제 설정입니다. |
data.settings.customVoice | 선택적인 맞춤 음성 설정입니다. |
data.settings.customVoiceId | 선택적인 맞춤 음성 식별자입니다. |
data.settings.keepBackgroundMusic | 선택적인 배경 오디오 설정입니다. |
data.settings.keepOriginalVoice | 선택적인 원본 음성 설정입니다. |
data.settings.originalVoiceVolume | 선택적인 원본 음성 볼륨입니다. |
data.settings.activeSpeakerDetectionEnabled | 선택적인 활성 화자 감지 설정입니다. |
data.settings.subtitles | 선택적인 {isEnable,source} 자막 설정입니다. |
data.settings.smartSync | 선택적인 SmartSync 설정입니다. |
data.settings.voiceIsolatorOption | 선택적인 studio 또는 realistic 음성 분리 설정입니다. |
data.settings.voiceCloningSettings | 선택적인 {stability,similarity} 음성 복제 설정입니다. |
data.error | 프로젝트 수준의 처리 실패에 대한 선택적인 공개 {code,message}입니다. |
data.translations[].workId | 이 버전이 포함된 언어 작업 식별자입니다. |
data.translations[].translatedVersionId | 특정 더빙 출력 버전의 식별자입니다. |
data.translations[].targetLanguage | 버전의 대상 언어이며, 값이 없으면 해당 언어 작업의 언어를 사용합니다. |
data.translations[].status | 저장된 버전 상태: not-started, in-progress, completed 또는 failed입니다. |
data.translations[].currentStep | 선택적인 더빙 파이프라인 단계입니다. progress는 선택적인 숫자 진행률 값입니다. |
data.translations[].progress | 선택적인 더빙 진행률 값입니다. |
data.translations[].createdAt | Unix 밀리초로 정규화한 생성 시점이며, 값이 없으면 언어 작업 생성 시점을 사용합니다. |
data.translations[].completedAt | 선택적인 Unix 밀리초 단위 완료 시점입니다. |
data.translations[].failedAt | 선택적인 Unix 밀리초 단위 실패 시점입니다. |
data.translations[].timedOutAt | 선택적인 Unix 밀리초 단위 시간 초과 시점입니다. |
data.translations[].translatedVideoUrl | 저장된 번역 동영상 URL이며, 사용할 수 없으면 빈 문자열입니다. |
data.translations[].translatedAudioUrl | 저장된 번역 오디오 URL이며, 사용할 수 없으면 빈 문자열입니다. |
data.translations[].error | 버전이 실패한 경우의 선택적인 {code,message}입니다. |
data.translations[].settings | 공개 버전 설정: voiceCloning, uploadType, keepBackgroundMusic, keepOriginalVoice, originalVoiceVolume, subtitles, smartSync, dubbingMode, voiceIsolatorOption 및 선택적인 translationQualityMode, cutBecauseFreeUser, originalDurationSeconds, cutDurationSeconds, voiceCloningSettings입니다. |
data.translations[].settings.dubbingMode | translate 또는 dub-only입니다. dub-only 버전에서는 SmartSync가 false입니다. |
data.translations[].lipSync | 선택적인 {latest,history}입니다. 각 항목에는 jobId, status, videoUrl, errorMessage, type, createdAt 및 선택적인 requestedAt, retryRequestedAt, completedAt, failedAt, timedOutAt, activeSpeakerDetectionEnabled, isRetried가 있습니다. 립싱크 시점은 ISO 문자열로 저장됩니다. |
data.translations[].dynamicSubtitles | used, inProgress, magicZooms, magicBrolls, magicBrollsPercentage, videoUrl, errorMessage 및 선택적인 removeSilencePace, removeBadTakes, templateName, requestedAt, rerunCount를 포함하는 선택적인 객체입니다. requestedAt의 단위는 Unix 밀리초입니다. |
data.translations[].publicationAttempts | 공개 게시 시도의 선택적 배열입니다. id, status, origin 및 선택적 scheduledAt, processingStartedAt, publishedAt, failedAt, privacyStatus, url, videoId, errorMessage가 포함됩니다. |
data.translations[].publishedVideos | type, videoId, privacyStatus와 선택적 url, datePublished, origin, scheduledAt, plannedPublicationId가 포함된 선택적 배열입니다. |
이 요청 복구 및 폴링
연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.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":"projects_update"}'
HTTP 200
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_update",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"projectId": "project_launch_2026",
"projectName": "Product launch — English",
"status": "success",
"workflow": "translation",
"originalVideoUrl": "https://media.example.com/launch/original.mp4",
"originalLanguage": "fr",
"targetLanguages": ["english"],
"duration": 75,
"createdAt": 1792152000000,
"progress": {
"step": "done",
"transcriptionProgress": 100,
"transcriptionStatus": "success"
},
"translations": [
{
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"translatedVersionId": "0fa684f3-4997-4d7a-9424-16d1f9ac849c",
"targetLanguage": "english",
"status": "completed",
"currentStep": "done",
"progress": 100,
"createdAt": 1792152060000,
"completedAt": 1792152300000,
"translatedVideoUrl": "https://media.example.com/launch/english.mp4",
"translatedAudioUrl": "https://media.example.com/launch/english.mp3",
"settings": {
"voiceCloning": true,
"uploadType": "video",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"subtitles": {
"isEnable": false,
"source": "translated"
},
"smartSync": true,
"dubbingMode": "translate",
"voiceIsolatorOption": "studio"
}
}
],
"segmentStructureRevision": 3,
"numberOfSpeakers": 1,
"translationInstructions": "Keep product names unchanged.",
"isReadyForDubbing": true,
"settings": {
"voiceCloning": true,
"customVoice": false,
"customVoiceId": "",
"keepBackgroundMusic": true,
"keepOriginalVoice": false,
"originalVoiceVolume": 30,
"activeSpeakerDetectionEnabled": false,
"subtitles": {
"isEnable": true,
"source": "translated"
},
"smartSync": true,
"voiceIsolatorOption": "studio",
"voiceCloningSettings": {
"stability": 0.5,
"similarity": 0.75
}
}
}
}
}
작업 참고 사항
- changes에는 지원되는 필드가 최소 하나 포함되어야 합니다. 나열되지 않은 속성은 거부됩니다. 생략된 필드는 변경되지 않습니다.
- changes 객체는 projectName, translationInstructions, isReadyForDubbing, voiceCloning, keepBackgroundMusic, keepOriginalVoice, originalVoiceVolume, activeSpeakerDetectionEnabled, smartSync, voiceIsolatorOption, voiceCloningSettings 및 subtitles를 지원합니다.
- originalVoiceVolume은 1에서 70 사이입니다. voiceCloningSettings에는 0에서 1 사이의 stability와 similarity가 모두 포함되어야 하며, subtitles에는 isEnable과 source가 모두 포함되어야 합니다.
- 설정과 교정 준비 상태를 업데이트합니다. 이 액션 자체로 이전에 완료된 미디어를 다시 생성하지는 않습니다. 결과는 projects_get과 동일한 공개 필드 구성을 사용합니다.
- 저장된 실패는 VoiceCheap 오류 코드와 고정 메시지를 반환합니다. 코드와 현재 리소스 상태를 사용해 복구 방법을 결정하세요.
사용량
성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.오류
| HTTP 상태 | 코드 | 의미 또는 복구 방법 |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | 자격 증명이 access_token 또는 api_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요. |
| 400 | IDEMPOTENCY_CONFLICT | Idempotency-Key 헤더와 본문의 requestId 필드가 일치해야 합니다. |
| 400 | INVALID_REQUEST_ID | UUID v4인 requestId 또는 Idempotency-Key를 제공하세요. |
| 400 | VALIDATION_ERROR | 스키마에 따라 입력을 수정하세요. 유효하지 않거나 일관되지 않은 값은 실행 전에 거부됩니다. |
| 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 | FORBIDDEN | 인증된 작업 수행자가 이 프로젝트에 접근할 수 없습니다. |
| 403 | INSUFFICIENT_SCOPE | 필요한 모든 권한을 부여하거나 다른 자격 증명을 사용하세요. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | 계정의 통합 한도를 확인할 수 없습니다. |
| 403 | SUBSCRIPTION_REQUIRED | 활성 유료 구독을 사용하세요. |
| 403 | TEAM_OWNER_NOT_FOUND | 실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다. |
| 404 | PROJECT_NOT_FOUND | 접근 가능한 계정에 프로젝트가 없습니다. |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | 이 계정에서는 이미 10개의 연동 액션이 실행 중입니다. 새 액션을 시작하기 전에 기존 요청을 폴링하세요. |
| 409 | IDEMPOTENCY_CONFLICT | 동일한 작업과 인수에 대해서만 식별자를 재사용하세요. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | 월간 한도가 초기화될 때까지 기다리거나 요금제를 변경하세요. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Retry-After가 있으면 지정된 시간만큼 기다리고 백오프를 적용하세요. |
| 500 | INTERNAL_ERROR | 변경 작업을 재시도하기로 결정하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. |
| 503 | ACTION_RESULT_UNAVAILABLE | 액션은 실행되었지만 결과를 저장할 수 없습니다. 새 생성을 시작하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. |
| 503 | SERVER_RESTARTING | 서버가 다시 시작 중입니다. 잠시 후 재시도하고, 변경 작업의 경우 동일한 요청 식별자를 유지하세요. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["projects:write"]
}
}
이 페이지가 도움이 되었나요?

