> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Übersetzungsstatus abrufen

> Überprüfen Sie den Status eines Übersetzungsprojekts und rufen Sie die Ergebnisse ab

# Übersetzungsstatus abrufen

Rufen Sie den aktuellen Status eines Übersetzungsprojekts ab. Verwenden Sie diesen Endpunkt, um den Fortschritt abzufragen und die URL des übersetzten Videos zu erhalten, sobald die Verarbeitung abgeschlossen ist.

## Anfrage

### Header

<ParamField header="x-api-key" type="string" required>
  Ihr VoiceCheap API-Schlüssel. Erhalten Sie einen unter [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api).
</ParamField>

### Pfadparameter

<ParamField path="projectId" type="string" required>
  Die eindeutige Kennung des Übersetzungsprojekts, die vom [Start Translation](/docs/de/api-reference/translate)-Endpunkt zurückgegeben wird.
</ParamField>

## Antwort

Die Antwortstruktur variiert je nach Übersetzungsstatus.

### Allgemeine Felder

<ResponseField name="projectId" type="string" required>
  Die eindeutige Kennung des Projekts
</ResponseField>

<ResponseField name="projectName" type="string" required>
  Der Name des Projekts
</ResponseField>

<ResponseField name="originalVideoUrl" type="string" required>
  URL zur ursprünglichen hochgeladenen Video-/Audiodatei
</ResponseField>

<ResponseField name="originalLanguage" type="string" required>
  Die erkannte oder angegebene Originalsprache
</ResponseField>

<ResponseField name="targetLanguage" type="string" required>
  Die Zielsprache für die Übersetzung
</ResponseField>

<ResponseField name="duration" type="number" required>
  Dauer des Inhalts in Sekunden
</ResponseField>

<ResponseField name="createdAt" type="number" required>
  Unix-Zeitstempel, zu dem das Projekt erstellt wurde
</ResponseField>

<ResponseField name="workflow" type="string" required>
  API-Workflow, der das Projekt erstellt hat: `translation` oder `transcription`.
</ResponseField>

<ResponseField name="transcriptionStatus" type="string" required>
  Status der Quelltranskription: `processing`, `success` oder `failed`. Dieses Signal ist unabhängig vom Abschluss der Synchronisation.
</ResponseField>

<ResponseField name="transcripts" type="object" required>
  Verfügbare normalisierte Transkripte.

  <Expandable title="Transkripteigenschaften">
    <ResponseField name="transcripts.original" type="object | null">
      Transkript in der Originalsprache, sofern verfügbar, einschließlich Zeitstempeln und Sprechern.
    </ResponseField>

    <ResponseField name="transcripts.translations" type="array">
      Verfügbare Transkripte in der Zielsprache mit ihren Sprach- und Arbeitskennungen.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="workId" type="string">
  Kennung der Übersetzungsarbeit für die aktuell gemeldete übersetzte Version.
</ResponseField>

<ResponseField name="translatedVersionId" type="string">
  Kennung der übersetzten Version für die aktuell gemeldete übersetzte Version.
</ResponseField>

<ResponseField name="actualProgressStep" type="string">
  Aktueller Projektschritt. Während der Erstellung oder Transkription spiegelt dies den aktiven Erstellungsschritt wider.
  Beispiele sind `downloading_content`, `content_validation` und `transcription_processing`.
  Sobald die Synchronisation beginnt, kann sie zu einem aktiven Synchronisationsschritt wie `smart_sync` oder `audio_assembling` wechseln.
  `status: processing` lässt sich nicht mit `actualProgressStep: done` kombinieren.
</ResponseField>

<ResponseField name="translationAndTranscriptionProgress" type="number">
  Ungefährer Fortschrittsprozentsatz für die Projekterstellung/-transkription (0-100)
</ResponseField>

<ResponseField name="dubbingStep" type="string">
  Aktueller Synchronisationsschritt für die Zielsprache (z. B. `smart_sync`, `audio_enhancement`, `video_upload`)
</ResponseField>

<ResponseField name="dubbingProgress" type="number">
  Ungefährer Fortschrittsprozentsatz für die Synchronisation (0-100)
</ResponseField>

<ResponseField name="status" type="string" required>
  Aktueller Status der Übersetzung: `processing`, `success` oder `failed`
</ResponseField>

### Lip Sync Felder

Wenn eine Lippensynchronisation angefordert wurde, enthält die Antwort ein zusätzliches `lipSync`-Objekt:

<ResponseField name="lipSync" type="object">
  Status und Details der Lippensynchronisation (nur vorhanden, wenn eine Lippensynchronisation angefordert wurde)

  <Expandable title="Lippensynchronisationseigenschaften">
    <ResponseField name="lipSync.jobId" type="string">
      Auftragskennung für die Lippensynchronisation
    </ResponseField>

    <ResponseField name="lipSync.status" type="string">
      Status der Lippensynchronisation: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REJECTED` oder `CANCELED`
    </ResponseField>

    <ResponseField name="lipSync.videoUrl" type="string">
      URL des lippensynchronisierten Videos. Verwenden Sie diese URL für das endgültige lippensynchronisierte Ergebnis, wenn `lipSync.status` den Wert `COMPLETED` hat.
    </ResponseField>

    <ResponseField name="lipSync.errorMessage" type="string">
      Fehlerdetails, falls die Lippensynchronisation fehlgeschlagen ist
    </ResponseField>

    <ResponseField name="lipSync.type" type="string">
      Modus der Lippensynchronisation: `standard`, `pro` oder `studio`.
    </ResponseField>

    <ResponseField name="lipSync.createdAt" type="string">
      ISO-Zeitstempel, zu dem der Versuch der Lippensynchronisation erstellt wurde.
    </ResponseField>

    <ResponseField name="lipSync.requestedAt" type="string">
      ISO-Zeitstempel, zu dem der Versuch der Lippensynchronisation angefordert wurde, sofern verfügbar.
    </ResponseField>

    <ResponseField name="lipSync.completedAt" type="string">
      ISO-Zeitstempel, zu dem die Lippensynchronisation abgeschlossen wurde, sofern verfügbar.
    </ResponseField>

    <ResponseField name="lipSync.failedAt" type="string">
      ISO-Zeitstempel, zu dem die Lippensynchronisation fehlgeschlagen ist, sofern verfügbar.
    </ResponseField>

    <ResponseField name="lipSync.timedOutAt" type="string">
      ISO-Zeitstempel, wann die Lippensynchronisation abgelaufen ist, falls verfügbar.
    </ResponseField>

    <ResponseField name="lipSync.activeSpeakerDetectionEnabled" type="boolean">
      Ob die Erkennung aktiver Sprecher für diesen Versuch der Lippensynchronisation aktiviert war.
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Wenn eine Lippensynchronisation angefordert wird, bleibt die Übersetzung in `processing`, bis `lipSync.status` `COMPLETED` ist. Wenn die Lippensynchronisation fehlschlägt, ändert sich der Status zu
  `failed` und `error.code` ist `LIPSYNC_FAILED`. Wenn die Lippensynchronisation erfolgreich ist, lesen Sie das lippensynchronisierte Asset von `lipSync.videoUrl`; `translatedVideoUrl`
  ist die übersetzte Videoausgabe vor dem Overlay der Lippensynchronisation.
</Info>

<Tip>Verwenden Sie `GET /v1/projects/{projectId}`, wenn Sie den vollständigen Verlauf der übersetzten Version oder den vollständigen Verlauf der Lippensynchronisation benötigen.</Tip>

### Felder für erfolgreiche Antworten

Für Übersetzungs-Workflows sind die folgenden Felder enthalten, wenn `status` `success` ist. Ein Workflow, der nur aus Transkription besteht, erreicht `success` ohne übersetzte Medienfelder.

<ResponseField name="translatedVideoUrl" type="string">
  URL zum Herunterladen der übersetzten Videodatei
</ResponseField>

<ResponseField name="translatedAudioUrl" type="string">
  URL zum separaten Herunterladen der übersetzten Audiodatei
</ResponseField>

### Felder für fehlerhafte Antworten

Wenn `status` `failed` ist, ist das folgende zusätzliche Feld enthalten:

<ResponseField name="error" type="object">
  Fehlerdetails

  <Expandable title="Fehlereigenschaften">
    <ResponseField name="error.code" type="string">
      Maschinenlesbarer Fehlercode
    </ResponseField>

    <ResponseField name="error.message" type="string">
      Menschenlesbare Fehlerbeschreibung
    </ResponseField>
  </Expandable>
</ResponseField>

## Beispiele

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.voicecheap.ai/v1/translate/abc123-def456-ghi789/status" \
    -H "x-api-key: vc_your-api-key"
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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;
  }
  ```
</CodeGroup>

## Antwortbeispiele

### Verarbeitungsstatus

```json theme={null}
{
  "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"
}
```

### Verarbeitungsstatus (Lip Sync angefordert)

```json theme={null}
{
  "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"
  }
}
```

### Erfolgsstatus

```json theme={null}
{
  "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/..."
}
```

### Erfolgsstatus (Lip Sync abgeschlossen)

```json theme={null}
{
  "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"
  }
}
```

### Fehlerstatus

```json theme={null}
{
  "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."
  }
}
```

## Best Practices für das Polling

<Info>
  **Empfohlenes Polling-Intervall:** 10-30 Sekunden

  Die Übersetzungszeit variiert je nach Videolänge und Komplexität. Rechnen Sie bei einem typischen 2-Minuten-Video mit 2-5 Minuten Verarbeitungszeit.
</Info>

<Warning>
  **Ratenbegrenzung:** 30 Anfragen pro Minute

  Vermeiden Sie es, häufiger als alle 2 Sekunden abzufragen, um innerhalb der Ratenbegrenzungen zu bleiben.
</Warning>

## Fehler

| Status | Code                  | Beschreibung                                      |
| ------ | --------------------- | ------------------------------------------------- |
| 401    | `INVALID_API_KEY`     | Der bereitgestellte API-Schlüssel ist ungültig    |
| 403    | `FORBIDDEN`           | Sie haben keinen Zugriff auf dieses Projekt       |
| 404    | `PROJECT_NOT_FOUND`   | Das angegebene Projekt existiert nicht            |
| 429    | `RATE_LIMIT_EXCEEDED` | Zu viele Anfragen (Limit: 30 Anfragen pro Minute) |