获取翻译状态
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": "<string>",
"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>"
}
}翻译
获取翻译状态
检查翻译项目的状态并检索结果
获取翻译状态
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": "<string>",
"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>"
}
}获取翻译状态
检索翻译项目的当前状态。使用此端点轮询进度,并在处理完成后获取翻译后的视频 URL。请求
标头
string
必填
您的 VoiceCheap API 密钥。请从 app.voicecheap.ai/page-api 获取。
路径参数
string
必填
从 Start Translation 端点返回的翻译项目的唯一标识符。
响应
响应结构根据翻译状态而变化。通用字段
string
必填
项目的唯一标识符
string
必填
项目名称
string
必填
原始上传视频/音频文件的 URL
string
必填
检测到或指定的原始语言
string
必填
翻译的目标语言
number
必填
内容时长(秒)
number
必填
项目创建时的 Unix 时间戳
string
必填
创建该项目的 API 工作流:
translation 或 transcription。string
必填
源转录状态:
processing、success 或 failed。此信号与配音完成情况无关。string
当前报告的翻译版本的翻译工作标识符。
string
当前报告的翻译版本的翻译版本标识符。
string
当前项目步骤。在创建或转录期间,这反映了活跃的创建步骤。
示例包括
downloading_content、content_validation 和 transcription_processing。
一旦配音开始,它可能会切换到活跃的配音步骤,例如 smart_sync 或 audio_assembling。
status: processing 不与 actualProgressStep: done 配对。number
项目创建/转录的近似进度百分比 (0-100)
string
目标语言的当前配音步骤(例如
smart_sync、audio_enhancement、video_upload)number
配音的近似进度百分比 (0-100)
string
必填
翻译的当前状态:
processing、success 或 failedLip Sync 字段
当请求口型同步时,响应包含一个额外的lipSync 对象:
object
口型同步状态和输出详情(仅在请求口型同步时出现)
显示 lipSync 属性
显示 lipSync 属性
string
口型同步作业标识符
string
口型同步状态:
PENDING、PROCESSING、COMPLETED、FAILED、REJECTED 或 CANCELEDstring
口型同步视频的 URL。当
lipSync.status 为 COMPLETED 时,请使用此 URL 获取最终的口型同步输出。string
如果口型同步失败,则显示错误详情
string
口型同步模式:
standard、pro 或 studio。string
创建口型同步尝试时的 ISO 时间戳。
string
请求口型同步尝试时的 ISO 时间戳(如果可用)。
string
口型同步完成时的 ISO 时间戳(如果可用)。
string
口型同步失败时的 ISO 时间戳(如果可用)。
string
口型同步超时时的 ISO 时间戳(如有)。
boolean
此口型同步尝试是否启用了主动说话者检测。
当请求口型同步时,翻译将保留在
processing 中,直到 lipSync.status 被 COMPLETED。如果口型同步失败,状态将变为
failed 且 error.code 为 LIPSYNC_FAILED。当口型同步成功时,从 lipSync.videoUrl 读取口型同步后的资产;translatedVideoUrl
是口型同步叠加之前的翻译视频输出。当您需要完整的翻译版本历史记录或完整的口型同步历史记录时,请使用
GET /v1/projects/{projectId}。成功响应字段
对于翻译工作流,当status 为 success 时,会包含以下字段。仅转录工作流会达到 success,且不包含翻译后的媒体字段。
string
下载翻译视频文件的 URL
string
单独下载翻译音频文件的 URL
失败响应字段
当status 为 failed 时,会包含以下附加字段:
示例
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;
}
响应示例
处理状态
{
"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"
}
处理状态(已请求 Lip Sync)
{
"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"
}
}
成功状态
{
"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/..."
}
成功状态(Lip Sync 已完成)
{
"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"
}
}
失败状态
{
"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": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
}
轮询最佳实践
建议轮询间隔: 10-30 秒翻译时间因视频长度和复杂程度而异。对于典型的 2 分钟视频,预计处理时间为 2-5 分钟。
速率限制: 每分钟 30 个请求避免轮询频率高于每 2 秒一次,以保持在速率限制范围内。
错误
| 状态 | 代码 | 描述 |
|---|---|---|
| 401 | INVALID_API_KEY | 提供的 API 密钥无效 |
| 403 | FORBIDDEN | 您无权访问此项目 |
| 404 | PROJECT_NOT_FOUND | 指定的项目不存在 |
| 429 | RATE_LIMIT_EXCEEDED | 请求过多(限制:每分钟 30 个请求) |
此页面对您有帮助吗?

