Skip to main content
POST
セグメントの音声再生成をキューに追加し、必要に応じてリップシンクも更新します。通常のメディアクレジットが適用されます。requestId には固定の UUID が必要です。segment_actions_list をポーリングしてください。

認証と権限

string
必須
このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP でのみ使用でき、この REST エンドポイントでは使用できません。
必要な権限: translations:write. 有効な有料サブスクリプションが必要です。権限によってチーム内のロール、リソースの所有権、メディアクレジット、プランの制限が変わることはありません。

パラメーター

string
必須
テキスト値。最小文字数: 1. 最大文字数: 200. パターン: ^[^/\\]+$.
string
必須
テキスト値。最小文字数: 1. 最大文字数: 200. パターン: ^[^/\\]+$.
string
必須
テキスト値。最小文字数: 1. 最大文字数: 200. パターン: ^[^/\\]+$.
integer
必須
整数値。最小値: 0. 最大値: 9007199254740991.
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}$.
string
テキスト値。最大文字数: 500.
boolean
真偽値。
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。

冪等性

変更操作ごとに、requestId または Idempotency-Key HTTP ヘッダーに UUID v4 を指定してください。ネットワーク障害後の再試行では、同じ識別子と同一の引数を使用します。両方を指定する場合は一致させる必要があります。保存済みリクエストを再取得しても、操作は再実行されず、月間呼び出し回数も追加で消費されません。失敗または中断したリクエストは自動的には再開されません。 すべての変更操作は、再試行時に同じリクエストがまだ実行中であれば、通常の初回実行が同期処理であっても HTTP 202 を返す場合があります。実行が完了していても resultStored が false の場合、再試行では元の結果ではなく、保存済みリクエストの状態を HTTP 200 で返します。出力は対応するドメインの履歴、結果、またはダウンロードアクションで取得してください。

リクエスト例

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

レスポンス

初回実行が成功すると、操作結果を data に格納して HTTP 200 を返します。同じリクエストを再送した場合は、代わりに保存済みリクエストの状態を返すことがあります。例はサポートされるレスポンスの一例であり、すべての任意フィールドを示すものではありません。 認可された翻訳バージョン内の1つのセグメントを再生成するための、キュー受付結果を返します。

結果フィールド

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

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

操作の注意事項

  • 対象の編集に 1 つの UUID v4 requestId を使用し、再試行時も同じ引数で再利用してください。jobId はこの requestId と一致します。
  • 受け入れ時には started または queued を返し、完了を示すものではありません。segment_actions_list をポーリングし、items[].id が jobId と一致する項目が completed、failed、cancelled になるまで確認した後、transcripts_get と projects_get を再取得してください。
  • queue.revision はキューの状態を追跡するもので、原文セグメント構造のリビジョンではありません。キューのアクションは受け入れ時の構造を記録します。後から互換性のない構造変更があると、その項目は SEGMENT_STRUCTURE_CHANGED で失敗する場合があります。
  • 論理的に同じセグメントを対象とする処理待ちアクションは、1件だけ受け付けられます。新しい requestId を使っても SEGMENT_ACTION_ALREADY_PENDING は回避できません。
  • キュー実行時の失敗は、成功済みの送信結果を変更せず、items[].status の failed と errorCode に表示されます。
  • workId と translatedVersionId は選択したプロジェクトに属し、相互に対応している必要があります。ワーカーは実行開始時に、現在のメディア、セグメント状態、権限、クレジットを確認します。
  • segmentTranslationInstructions は任意で、500 文字以内です。regenerateLipSync が true の場合、音声生成後に、そのバージョンで最後に使われたリップシンクモードでセグメントのリップシンク再生成を要求します。
  • 通常のメディアクレジットが適用されます。受付の成功は、再生成や任意のリップシンクの成功を意味しません。
  • キュー項目の完了後、projects_get と transcripts_get を更新してください。レスポンス自体には、新しい音声URLや動画URLは含まれません。
  • 送信、キャンセル、ポーリング、再実行を含むキュー応答には、アクションのメタデータのみが含まれます。文字起こしの内容は、必要な transcription:read 権限で transcripts_get を使用して取得してください。

使用量

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

エラー