Get Translation Status
curl --request GET \
--url https://api.voicecheap.ai/v1/translate/{projectId}/status \
--header 'x-api-key: <x-api-key>'import requests
url = "https://api.voicecheap.ai/v1/translate/{projectId}/status"
headers = {"x-api-key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};
fetch('https://api.voicecheap.ai/v1/translate/{projectId}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.voicecheap.ai/v1/translate/{projectId}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.voicecheap.ai/v1/translate/{projectId}/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.voicecheap.ai/v1/translate/{projectId}/status")
.header("x-api-key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.voicecheap.ai/v1/translate/{projectId}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"projectId": "<string>",
"projectName": "<string>",
"originalVideoUrl": "<string>",
"originalLanguage": "<string>",
"targetLanguage": "<string>",
"duration": 123,
"createdAt": 123,
"workflow": "<string>",
"transcriptionStatus": "<string>",
"transcripts": {
"transcripts.original": {},
"transcripts.translations": [
{}
]
},
"workId": "<string>",
"translatedVersionId": "<string>",
"actualProgressStep": "<string>",
"translationAndTranscriptionProgress": 123,
"dubbingStep": "<string>",
"dubbingProgress": 123,
"status": "<string>",
"lipSync": {
"lipSync.jobId": "<string>",
"lipSync.status": "<string>",
"lipSync.videoUrl": "<string>",
"lipSync.errorMessage": {},
"lipSync.type": "<string>",
"lipSync.createdAt": "<string>",
"lipSync.requestedAt": "<string>",
"lipSync.completedAt": "<string>",
"lipSync.failedAt": "<string>",
"lipSync.timedOutAt": "<string>",
"lipSync.activeSpeakerDetectionEnabled": true
},
"translatedVideoUrl": "<string>",
"translatedAudioUrl": "<string>",
"error": {
"error.code": "<string>",
"error.message": "<string>"
}
}Projects
Get Translation Status
Check the status of a translation project and retrieve results
Get Translation Status
curl --request GET \
--url https://api.voicecheap.ai/v1/translate/{projectId}/status \
--header 'x-api-key: <x-api-key>'import requests
url = "https://api.voicecheap.ai/v1/translate/{projectId}/status"
headers = {"x-api-key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};
fetch('https://api.voicecheap.ai/v1/translate/{projectId}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.voicecheap.ai/v1/translate/{projectId}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.voicecheap.ai/v1/translate/{projectId}/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.voicecheap.ai/v1/translate/{projectId}/status")
.header("x-api-key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.voicecheap.ai/v1/translate/{projectId}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"projectId": "<string>",
"projectName": "<string>",
"originalVideoUrl": "<string>",
"originalLanguage": "<string>",
"targetLanguage": "<string>",
"duration": 123,
"createdAt": 123,
"workflow": "<string>",
"transcriptionStatus": "<string>",
"transcripts": {
"transcripts.original": {},
"transcripts.translations": [
{}
]
},
"workId": "<string>",
"translatedVersionId": "<string>",
"actualProgressStep": "<string>",
"translationAndTranscriptionProgress": 123,
"dubbingStep": "<string>",
"dubbingProgress": 123,
"status": "<string>",
"lipSync": {
"lipSync.jobId": "<string>",
"lipSync.status": "<string>",
"lipSync.videoUrl": "<string>",
"lipSync.errorMessage": {},
"lipSync.type": "<string>",
"lipSync.createdAt": "<string>",
"lipSync.requestedAt": "<string>",
"lipSync.completedAt": "<string>",
"lipSync.failedAt": "<string>",
"lipSync.timedOutAt": "<string>",
"lipSync.activeSpeakerDetectionEnabled": true
},
"translatedVideoUrl": "<string>",
"translatedAudioUrl": "<string>",
"error": {
"error.code": "<string>",
"error.message": "<string>"
}
}Get Translation Status
Retrieve the current status of a translation project. Use this endpoint to poll for progress and get the translated video URL when processing is complete.Request
Headers
string
required
Your VoiceCheap API key. Get one from app.voicecheap.ai/page-api.
Path Parameters
string
required
The unique identifier of the translation project returned from the Start Translation endpoint.
A project created with Create Project switches to the
translation workflow as soon as
Dub Project is called on it: this endpoint then follows the latest dubbing run.Response
The response structure varies based on the translation status.Common Fields
string
required
The unique identifier of the project
string
required
The name of the project
string
required
URL to the original uploaded video/audio file
string
required
The detected or specified original language
string
required
The target language for translation
number
required
Duration of the content in seconds
number
required
Unix timestamp when the project was created
string
required
API workflow that created the project:
translation or transcription.string
required
Source-transcription status:
processing, success, or failed. This signal is independent from dubbing completion.object
required
Available normalized transcripts.
Show transcripts properties
Show transcripts properties
object | null
Original-language transcript when available, including timestamps and speakers.
array
Available target-language transcripts with their language and work identifiers. Translated segments carry
finalSpeedFactor once voiced (see Export Project Transcript).string
Translation work identifier for the currently reported translated version.
string
Translated version identifier for the currently reported translated version.
string
Current project step. During creation or transcription, this reflects the active creation step.
Examples include
downloading_content, content_validation, and transcription_processing.
Once dubbing starts, it may switch to an active dubbing step such as smart_sync or audio_assembling.
status: processing can appear with actualProgressStep: done while a later operation, such as lip sync, is still running.number
Approximate progress percentage for project creation/transcription (0-100)
string
Current dubbing step for the target language (e.g.
smart_sync, audio_enhancement, video_upload)number
Approximate progress percentage for dubbing (0-100)
string
required
Current status of the translation:
processing, success, or failedLip Sync Fields
When lip-sync was requested, the response includes an additionallipSync object:
object
Lip-sync status and output details (only present when lip-sync was requested)
Show lipSync properties
Show lipSync properties
string
Lip-sync job identifier
string
Lip-sync status:
PENDING, PROCESSING, COMPLETED, FAILED, REJECTED, or CANCELEDstring
URL of the lip-synced video. Use this URL for the final lip-synced output when
lipSync.status is COMPLETED.string | null
Fixed VoiceCheap failure message, or null when no failure is recorded.
string
Lip-sync mode:
standard, pro, or studio.string
ISO timestamp when the lip-sync attempt was created.
string
ISO timestamp when the lip-sync attempt was requested, when available.
string
ISO timestamp when lip-sync completed, when available.
string
ISO timestamp when lip-sync failed, when available.
string
ISO timestamp when lip-sync timed out, when available.
boolean
Whether active speaker detection was enabled for this lip-sync attempt.
When lip-sync is requested, the translation stays in
processing until lipSync.status is COMPLETED. If lip-sync fails, the status becomes
failed and the error.code is LIPSYNC_FAILED. When lip-sync succeeds, read the lip-synced asset from lipSync.videoUrl; translatedVideoUrl
is the translated video output before the lip-sync overlay.Use
GET /v1/projects/{projectId} when you need the full translated version history or complete lip-sync history.Success Response Fields
For translation workflows, the following fields are included whenstatus is success. A transcription-only workflow reaches success without translated media fields.
string
URL to download the translated video file
string
URL to download the translated audio file separately
Failed Response Fields
Whenstatus is failed, the following additional field is included:
object
Examples
curl -X GET "https://api.voicecheap.ai/v1/translate/abc123-def456-ghi789/status" \
-H "x-api-key: vc_your-api-key"
type TranslationStatus = 'processing' | 'success' | 'failed';
interface Transcript {
source: 'original' | 'translated';
language: string;
text: string;
segments: Array<{
index: number;
text: string;
begin: number;
end: number;
speaker: number;
}>;
}
interface TranslationStatusBase {
projectId: string;
projectName: string;
originalVideoUrl: string;
originalLanguage: string;
targetLanguage: string;
duration: number;
createdAt: number;
workflow: 'translation' | 'transcription';
transcriptionStatus: TranslationStatus;
transcripts: {
original: Transcript | null;
translations: Transcript[];
};
workId?: string;
translatedVersionId?: string;
actualProgressStep?: string;
translationAndTranscriptionProgress?: number;
dubbingStep?: string;
dubbingProgress?: number;
lipSync?: {
jobId: string;
status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REJECTED' | 'CANCELED';
videoUrl: string;
errorMessage: string | null;
type: 'standard' | 'pro' | 'studio';
createdAt?: string;
requestedAt?: string;
completedAt?: string;
failedAt?: string;
timedOutAt?: string;
activeSpeakerDetectionEnabled?: boolean;
};
}
interface TranslationStatusProcessing extends TranslationStatusBase {
status: 'processing';
}
interface TranslationStatusSuccess extends TranslationStatusBase {
status: 'success';
translatedVideoUrl?: string;
translatedAudioUrl?: string;
}
interface TranslationStatusFailed extends TranslationStatusBase {
status: 'failed';
error: {
code: string;
message: string;
};
}
type TranslationStatusResponse = TranslationStatusProcessing | TranslationStatusSuccess | TranslationStatusFailed;
async function getTranslationStatus(projectId: string): Promise<TranslationStatusResponse> {
const response = await fetch(`https://api.voicecheap.ai/v1/translate/${projectId}/status`, {
method: 'GET',
headers: {
'x-api-key': 'vc_your-api-key',
},
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || 'Failed to get status');
}
return response.json();
}
// Polling function with typed response handling
async function pollUntilComplete(projectId: string, intervalMs: number = 10000): Promise<TranslationStatusSuccess> {
while (true) {
const status = await getTranslationStatus(projectId);
if (status.status === 'success') {
return status;
}
if (status.status === 'failed') {
throw new Error(`Translation failed: ${status.error.message}`);
}
console.log('Still processing...');
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
}
// Usage
try {
const result = await pollUntilComplete('abc123-def456-ghi789');
console.log('Translated video:', result.translatedVideoUrl);
console.log('Translated audio:', result.translatedAudioUrl);
} catch (error) {
console.error('Error:', error);
}
const response = await fetch('https://api.voicecheap.ai/v1/translate/abc123-def456-ghi789/status', {
method: 'GET',
headers: {
'x-api-key': 'vc_your-api-key',
},
});
const status = await response.json();
if (status.status === 'success') {
console.log('Translated video:', status.translatedVideoUrl);
} else if (status.status === 'processing') {
console.log('Still processing...');
} else if (status.status === 'failed') {
console.error('Translation failed:', status.error.message);
}
import requests
import time
headers = {'x-api-key': 'vc_your-api-key'}
project_id = 'abc123-def456-ghi789'
# Poll until complete
while True:
response = requests.get(
f'https://api.voicecheap.ai/v1/translate/{project_id}/status',
headers=headers
)
status = response.json()
if status['status'] == 'success':
print(f"Translated video: {status['translatedVideoUrl']}")
print(f"Translated audio: {status['translatedAudioUrl']}")
break
elif status['status'] == 'failed':
print(f"Translation failed: {status['error']['message']}")
break
else:
print("Still processing...")
time.sleep(10) # Wait 10 seconds before polling again
<?php
$apiKey = 'vc_your-api-key';
$projectId = 'abc123-def456-ghi789';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.voicecheap.ai/v1/translate/{$projectId}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"x-api-key: {$apiKey}"
]
]);
$response = curl_exec($curl);
$status = json_decode($response, true);
switch ($status['status']) {
case 'success':
echo "Translated video: " . $status['translatedVideoUrl'] . "\n";
echo "Translated audio: " . $status['translatedAudioUrl'];
break;
case 'processing':
echo "Still processing...";
break;
case 'failed':
echo "Failed: " . $status['error']['message'];
break;
}
Response Examples
Processing Status
{
"projectId": "abc123-def456-ghi789",
"projectName": "My Spanish Translation",
"originalVideoUrl": "https://storage.voicecheap.ai/...",
"originalLanguage": "en",
"targetLanguage": "spanish",
"duration": 125.5,
"createdAt": 1702234567890,
"workflow": "translation",
"transcriptionStatus": "processing",
"transcripts": { "original": null, "translations": [] },
"actualProgressStep": "downloading_content",
"translationAndTranscriptionProgress": 11,
"dubbingStep": "smart_sync",
"dubbingProgress": 30,
"status": "processing"
}
Processing Status (Lip Sync Requested)
{
"projectId": "abc123-def456-ghi789",
"projectName": "My Spanish Translation",
"originalVideoUrl": "https://storage.voicecheap.ai/...",
"originalLanguage": "en",
"targetLanguage": "spanish",
"duration": 125.5,
"createdAt": 1702234567890,
"workflow": "translation",
"transcriptionStatus": "success",
"transcripts": { "original": null, "translations": [] },
"actualProgressStep": "finalizing",
"translationAndTranscriptionProgress": 95,
"dubbingStep": "video_upload",
"dubbingProgress": 95,
"status": "processing",
"lipSync": {
"jobId": "syncjob_123",
"status": "PROCESSING",
"videoUrl": "",
"errorMessage": null,
"type": "standard"
}
}
Success Status
{
"projectId": "abc123-def456-ghi789",
"projectName": "My Spanish Translation",
"originalVideoUrl": "https://storage.voicecheap.ai/...",
"originalLanguage": "en",
"targetLanguage": "spanish",
"duration": 125.5,
"createdAt": 1702234567890,
"workflow": "translation",
"transcriptionStatus": "success",
"transcripts": { "original": null, "translations": [] },
"status": "success",
"translatedVideoUrl": "https://storage.voicecheap.ai/translated/...",
"translatedAudioUrl": "https://storage.voicecheap.ai/audio/..."
}
Success Status (Lip Sync Completed)
{
"projectId": "abc123-def456-ghi789",
"projectName": "My Spanish Translation",
"originalVideoUrl": "https://storage.voicecheap.ai/...",
"originalLanguage": "en",
"targetLanguage": "spanish",
"duration": 125.5,
"createdAt": 1702234567890,
"workflow": "translation",
"transcriptionStatus": "success",
"transcripts": { "original": null, "translations": [] },
"actualProgressStep": "done",
"dubbingStep": "done",
"dubbingProgress": 100,
"status": "success",
"translatedVideoUrl": "https://storage.voicecheap.ai/translated/...",
"translatedAudioUrl": "https://storage.voicecheap.ai/audio/...",
"lipSync": {
"jobId": "syncjob_123",
"status": "COMPLETED",
"videoUrl": "https://storage.voicecheap.ai/lipsync/...",
"errorMessage": null,
"type": "pro"
}
}
Failed Status
{
"projectId": "abc123-def456-ghi789",
"projectName": "My Spanish Translation",
"originalVideoUrl": "https://storage.voicecheap.ai/...",
"originalLanguage": "en",
"targetLanguage": "spanish",
"duration": 125.5,
"createdAt": 1702234567890,
"workflow": "translation",
"transcriptionStatus": "failed",
"transcripts": { "original": null, "translations": [] },
"status": "failed",
"error": {
"code": "TRANSCRIPTION_FAILED",
"message": "The transcription could not be completed. Please try again."
}
}
Polling Best Practices
Recommended polling interval: 10-30 secondsTranslation time varies based on video length and complexity. For a typical 2-minute video, expect 2-5 minutes of processing time.
Rate Limit: 30 requests per minuteAvoid polling more frequently than once every 2 seconds to stay within rate limits.
Errors
| Status | Code | Description |
|---|---|---|
| 401 | INVALID_API_KEY | The provided API key is invalid |
| 403 | FORBIDDEN | You don’t have access to this project |
| 404 | PROJECT_NOT_FOUND | The specified project does not exist |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests (limit: 30 requests per minute) |
Was this page helpful?

