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

# 翻訳先言語を追加

> 有料のメディア生成を開始せずに、既存のプロジェクトに空の翻訳先言語データを追加します。

有料のメディア生成を開始せずに、既存のプロジェクトに空の翻訳先言語データを追加します。

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/translations_add
```

## 認証と権限

<ParamField header="x-api-key" type="string" required>
  このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP
  でのみ使用でき、この REST エンドポイントでは使用できません。
</ParamField>

必要な権限: `translations:write`.

有効な有料サブスクリプションが必要です。権限によってチーム内のロール、リソースの所有権、メディアクレジット、プランの制限が変わることはありません。

## パラメーター

<ParamField body="projectId" type="string" required>
  テキスト値。

  最小文字数: 1. 最大文字数: 200. パターン: `^[^/\\]+$`.
</ParamField>

<ParamField body="targetLanguage" type="string" required>
  テキスト値。

  許容値: "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "azerbaijani", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "british english", "estonian", "finnish", "french", "french canadian", "galician", "german", "greek", "gujarati", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "irish", "italian", "japanese", "kannada", "kazakh", "khmer", "korean", "lao", "latvian", "lithuanian", "macedonian", "malay", "malayalam", "mandarin", "marathi", "mongolian", "nepali", "norwegian", "persian", "polish", "portuguese", "brazilian portuguese", "pt\_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu".
</ParamField>

<ParamField body="requestId" type="string">
  トランスポート境界では任意です。省略すると、検証前にサーバーが識別子を補完します。レスポンスを受信できなかった場合に安全に復旧できるよう、固定の UUID v4 を指定してください。

  形式: "uuid". パターン: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`.
</ParamField>

<Accordion title="完全な入力スキーマ">
  以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "projectId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "pattern": "^[^/\\\\]+$"
      },
      "targetLanguage": {
        "type": "string",
        "enum": [
          "afrikaans",
          "albanian",
          "amharic",
          "arabic",
          "armenian",
          "assamese",
          "azerbaijani",
          "basque",
          "belarusian",
          "bengali",
          "bosnian",
          "bulgarian",
          "catalan",
          "croatian",
          "czech",
          "danish",
          "dutch",
          "english",
          "british english",
          "estonian",
          "finnish",
          "french",
          "french canadian",
          "galician",
          "german",
          "greek",
          "gujarati",
          "hebrew",
          "hindi",
          "hungarian",
          "icelandic",
          "indonesian",
          "irish",
          "italian",
          "japanese",
          "kannada",
          "kazakh",
          "khmer",
          "korean",
          "lao",
          "latvian",
          "lithuanian",
          "macedonian",
          "malay",
          "malayalam",
          "mandarin",
          "marathi",
          "mongolian",
          "nepali",
          "norwegian",
          "persian",
          "polish",
          "portuguese",
          "brazilian portuguese",
          "pt_brazil",
          "punjabi",
          "romanian",
          "russian",
          "serbian",
          "slovak",
          "slovenian",
          "spanish",
          "swahili",
          "swedish",
          "tagalog",
          "tamil",
          "telugu",
          "thai",
          "turkish",
          "ukrainian",
          "urdu",
          "vietnamese",
          "welsh",
          "yoruba",
          "zulu"
        ]
      },
      "requestId": {
        "type": "string",
        "format": "uuid",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
        "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
      }
    },
    "required": ["projectId", "targetLanguage"],
    "additionalProperties": false
  }
  ```
</Accordion>

## 冪等性

変更操作ごとに、requestId または Idempotency-Key HTTP ヘッダーに UUID v4 を指定してください。ネットワーク障害後の再試行では、同じ識別子と同一の引数を使用します。両方を指定する場合は一致させる必要があります。保存済みリクエストを再取得しても、操作は再実行されず、月間呼び出し回数も追加で消費されません。失敗または中断したリクエストは自動的には再開されません。

すべての変更操作は、再試行時に同じリクエストがまだ実行中であれば、通常の初回実行が同期処理であっても HTTP 202 を返す場合があります。実行が完了していても resultStored が false の場合、再試行では元の結果ではなく、保存済みリクエストの状態を HTTP 200 で返します。出力は対応するドメインの履歴、結果、またはダウンロードアクションで取得してください。

## リクエスト例

例に記載されたリソース識別子とメディアキーを、ご自身のアカウントで返された値に置き換えてください。同じ変更操作を再試行する場合は、リクエスト識別子を変更しないでください。

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/translations_add' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"projectId":"project_launch_2026","targetLanguage":"english","requestId":"41321bda-e243-4b6f-96a4-622cd047c991"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    projectId: 'project_launch_2026',
    targetLanguage: 'english',
    requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_add', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VOICECHEAP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.code + ': ' + body.message);
  console.log(body);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.voicecheap.ai/v1/actions/translations_add",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"projectId": "project_launch_2026", "targetLanguage": "english", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## レスポンス

初回実行が成功すると、操作結果を data に格納して HTTP 200 を返します。同じリクエストを再送した場合は、代わりに保存済みリクエストの状態を返すことがあります。例はサポートされるレスポンスの一例であり、すべての任意フィールドを示すものではありません。

新しい言語別作業の識別情報を返します。その翻訳先言語がすでに存在する場合は、既存作業の公開フィールド全体を返します。

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "projectId": "project_launch_2026",
      "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
      "targetLanguage": "english"
    },
    "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
  }
  ```

  ```json HTTP 202 replay_running theme={null}
  {
    "data": {
      "requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
      "operation": "translations_add",
      "createdAt": 1792144800000,
      "updatedAt": 1792144820000,
      "status": "running",
      "pollAfterSeconds": 5
    },
    "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
  }
  ```

  ```json HTTP 200 replay_completed_without_result theme={null}
  {
    "data": {
      "requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
      "operation": "translations_add",
      "createdAt": 1792144800000,
      "updatedAt": 1792144820000,
      "status": "completed",
      "resultStored": false,
      "message": "The action completed. Retrieve its output from the corresponding history or resource action."
    },
    "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
  }
  ```
</ResponseExample>

## 結果フィールド

| フィールド | 説明 |
| - | - |
| `data.workId` | 言語ワークの識別子。 |
| `data.projectId` | 親プロジェクトの識別子。 |
| `data.targetLanguage` | 対象言語。 |
| `data.originalLanguage` | ソース言語。 |
| `data.createdAt` | Unix ミリ秒に正規化した言語別ワークの作成時刻。 |
| `data.isWorkWaitingForProofreading` | 校正状態。明示的に設定されていない場合は false。 |
| `data.pendingSegmentIndexes` | まだ翻訳待ちの原文セグメントのインデックス。デフォルトは空の配列。 |
| `data.versions` | この作業に含まれるすべての公開バージョン。新しい順。 |
| `data.versions[].workId` | このバージョンを含む言語ワークの識別子。 |
| `data.versions[].translatedVersionId` | 特定の吹き替え出力バージョンの識別子。 |
| `data.versions[].targetLanguage` | バージョンの翻訳先言語。未設定の場合は言語別作業データの言語を使用します。 |
| `data.versions[].status` | 保存済みバージョンの状態：not-started、in-progress、completed、failed。 |
| `data.versions[].currentStep` | 任意の吹き替えパイプラインのステップ。progress は任意の数値の進捗値です。 |
| `data.versions[].progress` | 任意の吹き替え進捗の値。 |
| `data.versions[].createdAt` | Unix ミリ秒に正規化された作成時刻。未設定の場合は言語別作業データの作成時刻を使用します。 |
| `data.versions[].completedAt` | 任意の完了時刻。Unix ミリ秒。 |
| `data.versions[].failedAt` | 任意の失敗時刻。Unix ミリ秒。 |
| `data.versions[].timedOutAt` | 任意のタイムアウト時刻。Unix ミリ秒。 |
| `data.versions[].translatedVideoUrl` | 保存済みの翻訳動画 URL。利用できない場合は空文字列。 |
| `data.versions[].translatedAudioUrl` | 保存済みの翻訳音声 URL。利用できない場合は空文字列。 |
| `data.versions[].error` | バージョンが失敗した場合の、任意の \{code,message}。 |
| `data.versions[].settings` | 公開バージョン設定：voiceCloning、uploadType、keepBackgroundMusic、keepOriginalVoice、originalVoiceVolume、subtitles、smartSync、dubbingMode、voiceIsolatorOption、および任意の translationQualityMode、cutBecauseFreeUser、originalDurationSeconds、cutDurationSeconds、voiceCloningSettings。 |
| `data.versions[].settings.dubbingMode` | translate または dub-only。dub-only バージョンでは SmartSync は false です。 |
| `data.versions[].lipSync` | 任意の \{latest,history}。各項目は jobId、status、videoUrl、errorMessage、type、createdAt、および任意の requestedAt、retryRequestedAt、completedAt、failedAt、timedOutAt、activeSpeakerDetectionEnabled、isRetried を含みます。リップシンクの時刻は ISO 文字列として保存されます。 |
| `data.versions[].dynamicSubtitles` | 任意のオブジェクト。used、inProgress、magicZooms、magicBrolls、magicBrollsPercentage、videoUrl、errorMessage、および任意の removeSilencePace、removeBadTakes、templateName、requestedAt、rerunCount を含みます。requestedAt は Unix ミリ秒です。 |
| `data.versions[].publicationAttempts` | 任意の公開試行の配列。id、status、origin、および任意の scheduledAt、processingStartedAt、publishedAt、failedAt、privacyStatus、url、videoId、errorMessage を含みます。 |
| `data.versions[].publishedVideos` | type、videoId、privacyStatus と、任意の url、datePublished、origin、scheduledAt、plannedPublicationId を含む任意の配列。 |

## このプロジェクトには、対象言語のワークが既に存在します。

既存の言語ワークの投影結果全体を返します。追加のワークは作成しません。

```json HTTP 200 theme={null}
{
  "data": {
    "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
    "projectId": "project_launch_2026",
    "targetLanguage": "english",
    "originalLanguage": "fr",
    "createdAt": 1792152000000,
    "isWorkWaitingForProofreading": true,
    "pendingSegmentIndexes": [0, 1],
    "versions": []
  }
}
```

## リクエストの復旧とポーリング

接続が切断された後も同じ識別子を使用してください。resultStored が false の場合は、対応する履歴、結果、またはダウンロードアクションで出力を取得します。進捗を確認するためだけに、別の生成を開始しないでください。

```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","operation":"translations_add"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
    "operation": "translations_add",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "projectId": "project_launch_2026",
      "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
      "targetLanguage": "english"
    }
  }
}
```

## 操作の注意事項

* 新しい言語を追加しても、文字起こし、翻訳、音声生成は開始しません。新しいワークは校正待ちとなり、すべての原文セグメントのインデックスが保留中の状態で始まります。
* 新規作業の分岐は projectId、workId、targetLanguage だけを返します。既存作業の分岐は translations\_get と同じ公開フィールドを返します。
* 実際のメディア処理は translations\_start または translations\_dub で別途開始してください。
* 保存された失敗は、VoiceCheap のエラーコードと固定メッセージを返します。コードとリソースの現在の状態を使って、復旧方法を判断してください。

## 使用量

正常に実行された呼び出しごとに、月間 API/MCP 呼び出し回数を 1 回消費します。メディアクレジットと、その操作固有の生成枠も適用されます。

## エラー

| HTTP ステータス | コード | 意味または対処方法 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | access\_token または api\_key クエリパラメーターに認証情報が指定されています。認証情報はヘッダーで送信してください。 |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key ヘッダーとリクエストボディの requestId は一致させる必要があります。 |
| 400 | `INVALID_REQUEST_ID` | UUID v4 の requestId または Idempotency-Key を指定してください。 |
| 400 | `VALIDATION_ERROR` | スキーマに従って入力を修正してください。無効な値や整合性のない値は実行前に拒否されます。 |
| 401 | `API_KEY_EXPIRED` | API キーの有効期限が切れています。 |
| 401 | `INVALID_API_KEY` | 有効期限内の有効な API キーを指定してください。 |
| 401 | `INVALID_CREDENTIAL` | Authorization ヘッダーの形式が不正、または x-api-key と競合しています。 |
| 401 | `MISSING_CREDENTIAL` | 利用可能なヘッダー認証情報が指定されていないか、4096文字を超えています。 |
| 401 | `USER_NOT_FOUND` | 認証情報に対応するアカウントはすでに存在しません。 |
| 403 | `ACCOUNT_UNAVAILABLE` | 操作を実行するアカウントまたは請求対象アカウントが利用できないか、削除中です。 |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 認証情報のユーザーが複数のチームに属しているため、課金コンテキストが曖昧です。 |
| 403 | `FORBIDDEN` | 認証済み実行者は、このプロジェクトにアクセスできません。 |
| 403 | `INSUFFICIENT_SCOPE` | 必要な権限をすべて付与するか、別の認証情報を使用してください。 |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | アカウントの連携上限を確認できませんでした。 |
| 403 | `SUBSCRIPTION_REQUIRED` | 有効な有料サブスクリプションを使用してください。 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 実効的なチームオーナーのアカウントが見つかりませんでした。 |
| 404 | `PROJECT_NOT_FOUND` | アクセス可能なアカウントにこのプロジェクトは存在しません。 |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | このアカウントでは、すでに 10 件の連携アクションが実行中です。新しいアクションを開始する前に、既存のリクエストをポーリングしてください。 |
| 409 | `IDEMPOTENCY_CONFLICT` | 識別子を再利用する場合は、同じ操作と引数でのみ使用してください。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 月次リセットを待つか、プランを変更してください。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After がある場合は指定時間を待ち、バックオフを使用してください。 |
| 500 | `INTERNAL_ERROR` | 変更操作を再試行するか判断する前に、保存済みリクエストの状態とリソースの履歴を確認してください。 |
| 503 | `ACTION_RESULT_UNAVAILABLE` | アクションは実行されましたが、結果を保存できませんでした。新しい生成を開始する前に、保存済みリクエストの状態とリソース履歴を確認してください。 |
| 503 | `SERVER_RESTARTING` | サーバーが再起動中です。少し待ってから再試行し、変更操作では同じリクエスト識別子を使用してください。 |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["translations:write"]
  }
}
```


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