curl --request POST 'https://api.voicecheap.ai/v1/actions/translations_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","workId":"5f8423d1-e4c0-4f80-9e3f-eed959389e24"}'
const input = {
projectId: 'project_launch_2026',
workId: '5f8423d1-e4c0-4f80-9e3f-eed959389e24',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_get', {
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/translations_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"projectId": "project_launch_2026",
"targetLanguage": "english",
"originalLanguage": "fr",
"createdAt": 1792152000000,
"isWorkWaitingForProofreading": false,
"pendingSegmentIndexes": [],
"versions": [
{
"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"
}
}
]
}
}
Tłumaczenie i dubbing
Pobierz wersję językową
Pobierz metadane wersji językowej, indeksy oczekujących segmentów i ujednolicone wersje wynikowe.
POST
/
v1
/
actions
/
translations_get
curl --request POST 'https://api.voicecheap.ai/v1/actions/translations_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","workId":"5f8423d1-e4c0-4f80-9e3f-eed959389e24"}'
const input = {
projectId: 'project_launch_2026',
workId: '5f8423d1-e4c0-4f80-9e3f-eed959389e24',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_get', {
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/translations_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"projectId": "project_launch_2026",
"targetLanguage": "english",
"originalLanguage": "fr",
"createdAt": 1792152000000,
"isWorkWaitingForProofreading": false,
"pendingSegmentIndexes": [],
"versions": [
{
"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"
}
}
]
}
}
Pobierz metadane wersji językowej, indeksy oczekujących segmentów i ujednolicone wersje wynikowe.
Wymagane uprawnienia:
POST https://api.voicecheap.ai/v1/actions/translations_get
Uwierzytelnianie i uprawnienia
string
wymagane
Wyślij klucz API VoiceCheap w tym nagłówku. Obsługiwany jest również nagłówek Authorization: Bearer z tym samym kluczem API. Tokeny dostępu OAuth są
akceptowane tylko przez MCP, a nie przez ten endpoint REST.
projects:read.
Wymagana jest aktywna płatna subskrypcja. Uprawnienia nie zmieniają ról w zespole, własności zasobów, kredytów na multimedia ani limitów planu.
Parametry
string
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec:
^[^/\\]+$.string
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec:
^[^/\\]+$.Pełny schemat danych wejściowych
Pełny schemat danych wejściowych
Poniższy JSON Schema zachowuje dokładne nazwy pól, typy zagnieżdżone, wartości domyślne, ograniczenia i akceptowane wartości udostępniane przez mechanizm wykrywania. Dodatkowe reguły zależności między polami znajdują się w uwagach do operacji.
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"workId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
}
},
"required": ["projectId", "workId"],
"additionalProperties": false
}
Przykłady żądań
Zastąp przykładowe identyfikatory zasobów i klucze multimediów wartościami zwróconymi dla Twojego konta. Przy ponawianiu tej samej operacji zmieniającej dane zachowaj identyfikator żądania.curl --request POST 'https://api.voicecheap.ai/v1/actions/translations_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","workId":"5f8423d1-e4c0-4f80-9e3f-eed959389e24"}'
const input = {
projectId: 'project_launch_2026',
workId: '5f8423d1-e4c0-4f80-9e3f-eed959389e24',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_get', {
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/translations_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Odpowiedź
Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól. Zwraca jeden zestaw udostępnianych danych wersji językowej, do której jest przyznany dostęp, oraz jej publiczne wersje.{
"data": {
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"projectId": "project_launch_2026",
"targetLanguage": "english",
"originalLanguage": "fr",
"createdAt": 1792152000000,
"isWorkWaitingForProofreading": false,
"pendingSegmentIndexes": [],
"versions": [
{
"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"
}
}
]
}
}
Pola wyniku
| Pole | Opis |
|---|---|
data.workId | Identyfikator wersji językowej. |
data.projectId | Identyfikator projektu nadrzędnego. |
data.targetLanguage | Język docelowy. |
data.originalLanguage | Język źródłowy. |
data.createdAt | Czas utworzenia wersji językowej znormalizowany do milisekund Unix. |
data.isWorkWaitingForProofreading | Stan korekty; false, gdy nie został jawnie ustawiony. |
data.pendingSegmentIndexes | Indeksy segmentów źródłowych nadal oczekujących na tłumaczenie, domyślnie pusta tablica. |
data.versions | Wszystkie publiczne wersje w tej wersji językowej, uporządkowane od najnowszych. |
data.versions[].workId | Identyfikator wersji językowej zawierającej tę wersję. |
data.versions[].translatedVersionId | Identyfikator określonej wersji wyniku dubbingu. |
data.versions[].targetLanguage | Język docelowy wersji, z użyciem języka jej wersji językowej jako wartości zastępczej. |
data.versions[].status | Zapisany stan wersji: not-started, in-progress, completed lub failed. |
data.versions[].currentStep | Opcjonalny etap procesu dubbingu; progress to opcjonalna liczbowa wartość postępu. |
data.versions[].progress | Opcjonalna wartość postępu dubbingu. |
data.versions[].createdAt | Czas utworzenia ujednolicony do milisekund Unix; w razie braku używany jest czas utworzenia wersji językowej. |
data.versions[].completedAt | Opcjonalny czas ukończenia w milisekundach Unix. |
data.versions[].failedAt | Opcjonalny czas niepowodzenia w milisekundach Unix. |
data.versions[].timedOutAt | Opcjonalny czas przekroczenia limitu czasu w milisekundach Unix. |
data.versions[].translatedVideoUrl | Zapisany adres URL przetłumaczonego wideo lub pusty ciąg znaków, gdy jest niedostępny. |
data.versions[].translatedAudioUrl | Zapisany adres URL przetłumaczonego audio lub pusty ciąg znaków, gdy jest niedostępny. |
data.versions[].error | Opcjonalne {code,message}, gdy wersja zakończyła się błędem. |
data.versions[].settings | Publiczne ustawienia wersji: voiceCloning, uploadType, keepBackgroundMusic, keepOriginalVoice, originalVoiceVolume, subtitles, smartSync, dubbingMode, voiceIsolatorOption oraz opcjonalne translationQualityMode, cutBecauseFreeUser, originalDurationSeconds, cutDurationSeconds, voiceCloningSettings. |
data.versions[].settings.dubbingMode | translate lub dub-only. SmartSync ma wartość false dla wersji dub-only. |
data.versions[].lipSync | Opcjonalne {latest,history}; każdy wpis zawiera jobId, status, videoUrl, errorMessage, type, createdAt oraz opcjonalne requestedAt, retryRequestedAt, completedAt, failedAt, timedOutAt, activeSpeakerDetectionEnabled, isRetried. Czasy synchronizacji ruchu ust są zapisanymi ciągami znaków ISO. |
data.versions[].dynamicSubtitles | Opcjonalny obiekt z used, inProgress, magicZooms, magicBrolls, magicBrollsPercentage, videoUrl, errorMessage oraz opcjonalnymi removeSilencePace, removeBadTakes, templateName, requestedAt, rerunCount. requestedAt to czas Unix w milisekundach. |
data.versions[].publicationAttempts | Opcjonalna tablica publicznych prób publikacji: id, status, origin oraz opcjonalnie scheduledAt, processingStartedAt, publishedAt, failedAt, privacyStatus, url, videoId, errorMessage. |
data.versions[].publishedVideos | Opcjonalna tablica z type, videoId, privacyStatus oraz opcjonalnymi url, datePublished, origin, scheduledAt, plannedPublicationId. |
Uwagi do operacji
- workId musi należeć do projectId i mieć tego samego zapisanego właściciela projektu.
- pendingSegmentIndexes zawiera indeksy tekstów nadal wymagających tłumaczenia; ta lista jest niezależna od kolejki akcji segmentów.
- Zapisane błędy zwracają kody błędów VoiceCheap i stałe komunikaty. Użyj kodu i aktualnego stanu zasobu, aby zdecydować, jak wznowić działanie.
Wykorzystanie
Każde pomyślne wywołanie zużywa jedno wywołanie z miesięcznego limitu API/MCP. Obowiązują również kredyty na multimedia oraz limity generowania danej operacji.Błędy
| Status HTTP | Kod | Znaczenie lub sposób rozwiązania |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | Dane uwierzytelniające zostały podane w parametrze zapytania access_token lub api_key. Wysyłaj dane uwierzytelniające w nagłówkach. |
| 400 | VALIDATION_ERROR | Popraw dane wejściowe zgodnie ze schematem. Nieprawidłowe lub niespójne wartości są odrzucane przed wykonaniem. |
| 401 | API_KEY_EXPIRED | Klucz API wygasł. |
| 401 | INVALID_API_KEY | Podaj prawidłowy, niewygasły klucz API. |
| 401 | INVALID_CREDENTIAL | Nagłówek Authorization ma nieprawidłowy format lub jest sprzeczny z x-api-key. |
| 401 | MISSING_CREDENTIAL | Nie podano użytecznych danych uwierzytelniających w nagłówku lub przekroczyły one 4096 znaków. |
| 401 | USER_NOT_FOUND | Konto powiązane z poświadczeniem już nie istnieje. |
| 403 | AMBIGUOUS_TEAM_API_KEY | Użytkownik, do którego należą dane uwierzytelniające, należy do więcej niż jednego zespołu, więc kontekst rozliczeniowy jest niejednoznaczny. |
| 403 | FORBIDDEN | Uwierzytelniony podmiot wykonujący akcję nie ma dostępu do tego projektu. |
| 403 | INSUFFICIENT_SCOPE | Nadaj wszystkie wymagane uprawnienia lub wybierz inne dane uwierzytelniające. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | Nie udało się zweryfikować limitów integracji konta. |
| 403 | SUBSCRIPTION_REQUIRED | Użyj aktywnej płatnej subskrypcji. |
| 403 | TEAM_OWNER_NOT_FOUND | Nie znaleziono konta faktycznego właściciela zespołu. |
| 404 | PROJECT_NOT_FOUND | Projekt nie istnieje na dostępnym koncie. |
| 404 | TRANSLATION_NOT_FOUND | workId nie wskazuje wersji językowej należącej do tego projektu. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Poczekaj na odnowienie miesięcznego limitu lub zmień plan. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Jeśli występuje nagłówek Retry-After, odczekaj wskazany czas i stosuj rosnące odstępy między ponowieniami. |
| 500 | INTERNAL_ERROR | Sprawdź stan zapisanego żądania i historię zasobu przed podjęciem decyzji o ponowieniu operacji zmieniającej dane. |
| 503 | SERVER_RESTARTING | Serwer jest uruchamiany ponownie. Spróbuj ponownie wkrótce i zachowaj ten sam identyfikator żądania dla operacji zmieniającej dane. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["projects:read"]
}
}
Czy ta strona była pomocna?

