Skip to main content
プロジェクトの吹き替え

プロジェクトの吹き替え

用意した翻訳 SRT から、既存プロジェクトの音声を生成して出力をミックスします。このエンドポイントでは VoiceCheap は何も翻訳しません。翻訳エンジンも、SmartSync の言い換えも、用語集も使いません。各キューはプロジェクトの文字起こしの対応するセグメント上でそのまま読み上げられ、通常の翻訳と同じように元の背景音、字幕、任意のリップシンクとミックスされます。 翻訳を別の場所で作る場合(人間の翻訳者、独自のツール、自動化フロー)に使い、VoiceCheap には音声生成だけを任せます。実行は非同期です。翻訳ステータスの取得をポーリングするか、Webhookを受け取ります。

前提条件

  • プロジェクトが存在し、文字起こしが完了している必要があります。プロジェクトの作成(文字起こしのみ)または翻訳を開始で作成し、transcriptionStatus: "success" を待ってください。
  • SRT はプロジェクトの文字起こしを覆う必要があります。すべての文字起こしセグメントに少なくとも 1 つのキューが必要で、すべてのキューはいずれかのセグメント上になければなりません。プロジェクトのトランスクリプトをエクスポートで文字起こしを書き出し、タイムコードを保ったままキューごとに翻訳してください。
  • リクエストは同じメディアの翻訳と同じように、同じクレジット確認で請求されます。リップシンクのモードは通常どおり追加クレジットを消費します。

同時実行制限

プロジェクト作成、翻訳、吹き替えはいずれもアカウントの実行中翻訳数の上限(最大10件、アカウントによってはそれ未満)を確認します。枠を使用するのは進行中の翻訳または吹き替えだけで、文字起こし専用プロジェクトは枠を使用しません。上限に達すると、APIはCONCURRENT_TRANSLATION_LIMIT_REACHED(HTTP 429)を返します。適用される上限はdetails.limitで確認できます。 同じプロジェクトと対象言語で別の処理が進行中の場合、2件目の実行も拒否されます(TRANSLATION_ALREADY_IN_PROGRESS、HTTP 409)。

リクエスト

このエンドポイントは JSON ボディを受け取ります(Content-Type: application/json)。真偽値と数値のオプションは文字列ではなく JSON の値として送ります。

ヘッダー

string
必須
VoiceCheap APIキー。app.voicecheap.ai/page-apiから取得してください。

パスパラメータ

string
必須
プロジェクトの作成または翻訳を開始が返すプロジェクト識別子です。

ボディパラメータ

string
必須
translatedSrt の言語です。小文字で、翻訳を開始と同じ一覧から選びます。プロジェクトにこの言語の作業がまだない場合は作成され、言語がプロジェクトに追加されます。
string
必須
最終的なターゲット言語の SRT 内容です(キュー番号、タイミング行、テキスト)。最大 1,000,000 文字。キューはタイムスタンプで文字起こしセグメントに割り当てられます。セグメント開始から 50 ms 以内に始まるキューはそのセグメントへ、そうでなければ最も重なるセグメントへ割り当てます。1 つのセグメント上の複数キューは空白で結合します。読み上げる各セグメントのタイミング、話者、順序は常にプロジェクトの文字起こしから来ます。タイムコードは照合にだけ使います。
string
これ以降、このプロジェクトのWebhook イベントを受け取る https エンドポイントです。アカウントに設定されたエンドポイントを上書きします。デフォルト: まずプロジェクトに保存済みのエンドポイント、次にアカウントの Webhook エンドポイント。
boolean
生成した音声の下に、元の背景音声(音楽、環境音)を残します。デフォルト: true
boolean
生成した音声の下に、元の話者の声を小さく残します。デフォルト: false
number
keepOriginalVoice が有効なときの元の声の音量です。1 から 70 まで。デフォルト: 30
string
音声の方式:cloning(プロジェクトの話者の音声をクローンする)または custom(カタログの音声または自分の保存済みカスタム音声を使用する)。デフォルト: cloning
string
voiceMode が custom のときに必須です。dubbing_voices_list から、カタログの音声または認証済みアカウントが保存したカスタム音声の ID を使用してください。チームでの請求によって他のメンバーの保存済み音声にアクセスできるようにはなりません。
string
keepBackgroundMusic が有効なときの音声分離モードです。studio または realistic。デフォルト: studio
boolean
出力動画に字幕を焼き込みます。動画プロジェクトが必要です。デフォルト: false
string
subtitles が有効なときの字幕テキストです。translated(用意した SRT)または original(元の文字起こし)。デフォルト: translated
string
吹き替えの準備ができたらリップシンクを実行します。standard、pro、または studio。プラン、長さ、クレジットの規則は翻訳を開始と同じです。動画プロジェクトが必要です。デフォルト: リップシンクを省略するには、このフィールドを指定しません。
boolean
要求したリップシンク実行で、アクティブな話者の検出を有効にします。デフォルト: false
object
音声クローンの微調整です。stability と similarity を 0 から 1 の範囲で持つ JSON オブジェクトです。voiceMode: "cloning" のときだけ使えます。各値の説明は翻訳を開始を参照してください。
array
元の言語のままにするソース時間の範囲です。形式は [{ "startTime": 10.2, "endTime": 12.8 }]。動画プロジェクトと keepBackgroundMusic: true が必要で、keepOriginalVoice と併用できず、文字起こしセグメントと重ねることもできません。

レスポンス

boolean
必須
成功したリクエストでは常に true です。
string
必須
人が読める確認メッセージです。
string
必須
吹き替え中のプロジェクトです。
string
必須
targetLanguage に使う翻訳作業です。ステータス、詳細、文字起こしの各エンドポイントの workId と一致します。
number
必須
処理時間の概算(分)です。ソースメディアの開始した 1 分あたり処理 5 分です。
Response

実行の追跡

吹き替えが始まると、プロジェクトは translation ワークフローに切り替わります。そのため 翻訳ステータスの取得 は新しい実行を追跡します。status は processing から success(translatedVideoUrl と translatedAudioUrl 付き)または failed(error 付き)へ移ります。project.translation.completed と project.translation.failed の Webhook は同じ targetLanguage で送られます。プロジェクト詳細の取得 では、翻訳版が settings.dubbingMode: "dub-only" と settings.smartSync: false を報告します。 POST が受け付けられた後、対応付けの失敗は非同期で通知されます。ステータスエンドポイントは error.code と error.message を含む status: "failed" を返し、project.translation.failed Webhook にも同じコードとメッセージが含まれます。TRANSLATED_SRT_UNMATCHED_CUES のメッセージには対応しなかったキュー番号が、TRANSLATED_SRT_MISSING_SEGMENTS のメッセージにはキューのないセグメントのインデックスが示されます。これらの非同期応答には構造化された details は含まれません。SRT を修正して再度呼び出してください。失敗した版は履歴に残り、新しい版が作られます。

ペースを確認する

プロジェクトのトランスクリプトをエクスポートで翻訳済み文字起こしを JSON として書き出します。各セグメントには、生成された音声とセグメント枠の比率 finalSpeedFactor があります。おおよそ 1.3 を超えるキューを短くし、改訂した SRT でもう一度吹き替えてください。

フロー例

典型的な自動化(たとえば n8n や Make のシナリオ)は、エンドポイントを次の順でつなぎます。
  1. メディア、targetLanguage、明示的な originalLanguage を付けて POST /v1/projects(文字起こしのみ)。
  2. transcriptionStatus が success になるまで GET /v1/translate/{projectId}/status をポーリングするか、project.created Webhook を待ちます。
  3. { "source": "original", "outputFormat": "srt" } を付けて POST /v1/projects/{projectId}/transcript し、番号とタイムコードを保ったままキューを翻訳します。
  4. 翻訳した SRT を付けて POST /v1/projects/{projectId}/dub。
  5. status が success になるまでステータスエンドポイントをポーリングするか、project.translation.completed を待ちます。
  6. translatedVideoUrl をダウンロードします(リップシンクを要求した場合は lipSync.videoUrl)。
  7. 出力を手元に保存したら DELETE /v1/translate/{projectId}。

エラー

実行中に検出された対応の失敗(TRANSLATED_SRT_UNMATCHED_CUES、TRANSLATED_SRT_MISSING_SEGMENTS)は、このリクエストではなくステータスエンドポイントと失敗 Webhook が返します。