Get Translation Status

curl --request GET \
  --url https://api.voicecheap.ai/v1/translate/{projectId}/status \
  --header 'x-api-key: <x-api-key>'

{
  "projectId": "<string>",
  "projectName": "<string>",
  "originalVideoUrl": "<string>",
  "originalLanguage": "<string>",
  "targetLanguage": "<string>",
  "duration": 123,
  "createdAt": 123,
  "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>"
  },
  "translatedVideoUrl": "<string>",
  "translatedAudioUrl": "<string>",
  "error": {
    "error.code": "<string>",
    "error.message": "<string>"
  }
}

Get Translation Status

curl --request GET \
  --url https://api.voicecheap.ai/v1/translate/{projectId}/status \
  --header 'x-api-key: <x-api-key>'

{
  "projectId": "<string>",
  "projectName": "<string>",
  "originalVideoUrl": "<string>",
  "originalLanguage": "<string>",
  "targetLanguage": "<string>",
  "duration": 123,
  "createdAt": 123,
  "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>"
  },
  "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

x-api-key

string

required

Your VoiceCheap API key. Get one from app.voicecheap.ai/page-api.

Path Parameters

projectId

string

required

The unique identifier of the translation project returned from the Start Translation endpoint.

Response

The response structure varies based on the translation status.

Common Fields

projectId

string

required

The unique identifier of the project

projectName

string

required

The name of the project

originalVideoUrl

string

required

URL to the original uploaded video/audio file

originalLanguage

string

required

The detected or specified original language

targetLanguage

string

required

The target language for translation

duration

number

required

Duration of the content in seconds

createdAt

number

required

Unix timestamp when the project was created

actualProgressStep

string

Current project step. During creation/transcription this reflects those steps (e.g. downloading_content, content_validation, transcription_processing). Once dubbing starts, it may switch to the active dubbing step (e.g. smart_sync, audio_assembling) so status: processing does not pair with actualProgressStep: done.

translationAndTranscriptionProgress

number

Approximate progress percentage for project creation/transcription (0-100)

dubbingStep

string

Current dubbing step for the target language (e.g. smart_sync, audio_enhancement, video_upload)

dubbingProgress

number

Approximate progress percentage for dubbing (0-100)

status

string

required

Current status of the translation: processing, success, or failed

Lip Sync Fields

When lip-sync was requested, the response includes an additional lipSync object:

lipSync

object

Lip-sync status and output details (only present when lip-sync was requested)

Show lipSync properties

lipSync.jobId

string

Lip-sync job identifier

lipSync.status

string

Lip-sync status: PENDING, PROCESSING, COMPLETED, FAILED, REJECTED, or CANCELED

lipSync.videoUrl

string

URL of the lip-synced video. Use this URL for the final lip-synced output when lipSync.status is COMPLETED.

lipSync.errorMessage

string

Error details if lip-sync failed

lipSync.type

string

Lip-sync mode: standard, pro, or pro_2. POST /v1/translate can request standard or pro with lipsyncPro.

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.

Success Response Fields

When status is success, the following additional fields are included:

translatedVideoUrl

string

URL to download the translated video file

translatedAudioUrl

string

URL to download the translated audio file separately

Failed Response Fields

When status is failed, the following additional field is included:

error

object

Error details

Show error properties

error.code

string

Machine-readable error code

error.message

string

Human-readable error description

Examples

curl -X GET "https://api.voicecheap.ai/v1/translate/abc123-def456-ghi789/status" \
  -H "x-api-key: vc_your-api-key"

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,
  "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,
  "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,
  "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,
  "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,
  "status": "failed",
  "error": {
    "code": "TRANSCRIPTION_FAILED",
    "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
  }
}

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)

Start Translation Delete Project

​Get Translation Status

​Request

​Headers

​Path Parameters

​Response

​Common Fields

​Lip Sync Fields

​Success Response Fields

​Failed Response Fields

​Examples

​Response Examples

​Processing Status

​Processing Status (Lip Sync Requested)

​Success Status

​Success Status (Lip Sync Completed)

​Failed Status

​Polling Best Practices

​Errors

Get Translation Status

Request

Headers

Path Parameters

Response

Common Fields

Lip Sync Fields

Success Response Fields

Failed Response Fields

Examples

Response Examples

Processing Status

Processing Status (Lip Sync Requested)

Success Status

Success Status (Lip Sync Completed)

Failed Status

Polling Best Practices

Errors