> ## 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.

# 翻訳ステータスの取得

> 翻訳プロジェクトのステータスを確認し、結果を取得します

# 翻訳ステータスの取得

翻訳プロジェクトの現在のステータスを取得します。このエンドポイントを使用して進捗状況をポーリングし、処理完了時に翻訳済み動画のURLを取得します。

## リクエスト

### ヘッダー

**x-api-key** `string` *required*

VoiceCheap APIキー。[app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api)から取得してください。

### パスパラメータ

**projectId** `string` *required*

[Start Translation](https://api-docs.voicecheap.ai/docs/ja/api-reference/translate.md)エンドポイントから返される翻訳プロジェクトの一意の識別子。

> [!NOTE]
>
> [プロジェクトの作成](https://api-docs.voicecheap.ai/docs/ja/api-reference/create-project.md)で作成したプロジェクトは、[プロジェクトの吹き替え](https://api-docs.voicecheap.ai/docs/ja/api-reference/dub-project.md)が呼ばれると `translation` ワークフローに切り替わります。このエンドポイントはその最新の吹き替え実行を追跡します。

## レスポンス

レスポンス構造は翻訳ステータスによって異なります。

### 共通フィールド

**projectId** `string` *required*

プロジェクトの一意の識別子

**projectName** `string` *required*

プロジェクト名

**originalVideoUrl** `string` *required*

アップロードされた元の動画/音声ファイルのURL

**originalLanguage** `string` *required*

検出または指定された元の言語

**targetLanguage** `string` *required*

翻訳先の言語

**duration** `number` *required*

コンテンツの長さ（秒単位）

**createdAt** `number` *required*

プロジェクトが作成されたUnixタイムスタンプ

**workflow** `string` *required*

プロジェクトを作成したAPIワークフロー：`translation`または`transcription`。

**transcriptionStatus** `string` *required*

ソース文字起こしステータス：`processing`、`success`、または`failed`。このシグナルは吹き替えの完了とは独立しています。

**transcripts** `object` *required*

利用可能な正規化された文字起こし。

**transcriptsプロパティ**

**transcripts.original** `object | null`

利用可能な場合の、タイムスタンプと話者を含む元の言語の文字起こし。

**transcripts.translations** `array`

利用できるターゲット言語の文字起こしと、その言語および作業 ID です。翻訳セグメントは音声生成後に `finalSpeedFactor` を持ちます（[プロジェクトのトランスクリプトをエクスポート](https://api-docs.voicecheap.ai/docs/ja/api-reference/project-transcript.md)を参照）。

**workId** `string`

現在報告されている翻訳バージョンの翻訳作業識別子。

**translatedVersionId** `string`

現在報告されている翻訳バージョンの翻訳済みバージョン識別子。

**actualProgressStep** `string`

現在のプロジェクトステップ。作成中または文字起こし中は、アクティブな作成ステップを反映します。
例として、`downloading_content`、`content_validation`、`transcription_processing`などがあります。
吹き替えが開始されると、`smart_sync`や`audio_assembling`などのアクティブな吹き替えステップに切り替わることがあります。
後続のリップシンクなどが実行中の場合、`status: processing`と`actualProgressStep: done`が同時に返ることがあります。

**translationAndTranscriptionProgress** `number`

プロジェクト作成/文字起こしの概算進捗率（0-100）

**dubbingStep** `string`

翻訳先言語の現在の吹き替えステップ（例：`smart_sync`、`audio_enhancement`、`video_upload`）

**dubbingProgress** `number`

吹き替えの概算進捗率（0-100）

**status** `string` *required*

翻訳の現在のステータス：`processing`、`success`、または`failed`

### Lip Syncフィールド

リップシンクがリクエストされた場合、レスポンスには追加の`lipSync`オブジェクトが含まれます：

**lipSync** `object`

リップシンクのステータスと出力詳細（リップシンクがリクエストされた場合にのみ存在）

**lipSyncプロパティ**

**lipSync.jobId** `string`

リップシンクジョブ識別子

**lipSync.status** `string`

リップシンクステータス：`PENDING`、`PROCESSING`、`COMPLETED`、`FAILED`、`REJECTED`、または`CANCELED`

**lipSync.videoUrl** `string`

リップシンクされた動画のURL。`lipSync.status`が`COMPLETED`の場合、このURLを最終的なリップシンク出力として使用してください。

**lipSync.errorMessage** `string | null`

VoiceCheap の固定エラーメッセージ。失敗が記録されていない場合は null。

**lipSync.type** `string`

リップシンクモード：`standard`、`pro`、または`studio`。

**lipSync.createdAt** `string`

リップシンク試行が作成されたISOタイムスタンプ。

**lipSync.requestedAt** `string`

利用可能な場合の、リップシンク試行がリクエストされたISOタイムスタンプ。

**lipSync.completedAt** `string`

利用可能な場合の、リップシンクが完了したISOタイムスタンプ。

**lipSync.failedAt** `string`

利用可能な場合の、リップシンクが失敗したISOタイムスタンプ。

**lipSync.timedOutAt** `string`

リップシンクがタイムアウトした際のISOタイムスタンプ（利用可能な場合）。

**lipSync.activeSpeakerDetectionEnabled** `boolean`

このリップシンクの試行において、アクティブスピーカー検出が有効であったかどうか。

> [!NOTE]
>
> リップシンクがリクエストされると、翻訳は`lipSync.status`が`COMPLETED`になるまで`processing`の状態を維持します。リップシンクが失敗した場合、ステータスは
> `failed`となり、`error.code`は`LIPSYNC_FAILED`となります。リップシンクが成功した場合は、`lipSync.videoUrl`からリップシンク済みのアセットを読み取ってください。`translatedVideoUrl`
> は、リップシンクオーバーレイ適用前の翻訳済みビデオ出力です。

> [!TIP]
>
> 完全な翻訳バージョン履歴または完全なリップシンク履歴が必要な場合は、`GET /v1/projects/{projectId}`を使用してください。

### 成功時のレスポンスフィールド

翻訳ワークフローの場合、`status`が`success`のときに以下のフィールドが含まれます。文字起こしのみのワークフローでは、翻訳済みメディアフィールドを含まずに`success`に到達します。

**translatedVideoUrl** `string`

翻訳済みビデオファイルをダウンロードするためのURL

**translatedAudioUrl** `string`

翻訳済みオーディオファイルを個別にダウンロードするためのURL

### 失敗時のレスポンスフィールド

`status`が`failed`のとき、以下の追加フィールドが含まれます：

**error** `object`

エラーの詳細

**エラープロパティ**

**error.code** `string`

マシン可読なエラーコード

**error.message** `string`

人間が読める形式のエラー説明

## 例

```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;
}
```

## レスポンスの例

### 処理ステータス

```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"
}
```

### 処理ステータス（Lip Syncリクエスト済み）

```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"
  }
}
```

### 成功ステータス

```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/..."
}
```

### 成功ステータス（Lip Sync完了）

```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"
  }
}
```

### 失敗ステータス

```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": "The transcription could not be completed. Please try again."
  }
}
```

## ポーリングのベストプラクティス

> [!NOTE]
>
> **推奨ポーリング間隔：** 10〜30秒
>
> 翻訳時間はビデオの長さと複雑さによって異なります。一般的な2分間のビデオの場合、2〜5分の処理時間を見込んでください。

> [!WARNING]
>
> **レート制限：** 1分間に30リクエスト
>
> レート制限内に収めるため、2秒に1回を超える頻度でのポーリングは避けてください。

## エラー

| ステータス | コード | 説明 |
| - | - | - |
| 401 | `INVALID_API_KEY` | 提供されたAPIキーが無効です |
| 403 | `FORBIDDEN` | このプロジェクトへのアクセス権がありません |
| 404 | `PROJECT_NOT_FOUND` | 指定されたプロジェクトは存在しません |
| 429 | `RATE_LIMIT_EXCEEDED` | リクエストが多すぎます（制限：1分間に30リクエスト） |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.