Skip to main content
POST
明示的な許可を得た、ご自身が所有する 1~3 件の音声アップロードから、一時的なクローン音声プレビューを作成します。アプリのクローン試用枠が適用されます。保持するには、有効期限内に選択したプレビューを保存してください。

認証と権限

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

パラメーター

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
必須
テキスト値。最小文字数: 1. 最大文字数: 80.
array
必須
値のリスト。要素の構造は完全な入力スキーマを参照してください。最小要素数: 1. 最大要素数: 3.
boolean
必須
すべてのサンプルに含まれる声の人物について、クローンを作成する権限があることを確認してください。必須の値: true.
boolean
真偽値。デフォルト値: false.
string
テキスト値。最大文字数: 35. パターン: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。

冪等性

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

リクエスト例

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

レスポンス

この操作は実行中に HTTP 202 を返します。requestId を保存し、その識別子と元の操作名を指定して action_request_get をポーリングしてください。ポーリングの状態は running、completed、failed、interrupted です。完了した結果が別のメディアジョブを示す場合は、その操作に対応するステータスまたは出力取得アクションで処理を続けてください。 新しいクローン候補を含む、すべてのアクティブな未保存音声プレビューと更新後の作成利用枠。

結果フィールド

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

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

操作の注意事項

  • この変更操作には UUID v4 requestId を使用し、再試行時も同じ引数で再利用してください。長時間実行アクションは最初に running のリクエストを返します。この例は、action_request_get で取得できる完了済みハンドラー結果です。
  • 所有する音声サンプル 1–3 個をアップロードし、完了済みの fileKey を使用してください。対応形式は MP3、WAV、M4A、OGG、Opus です。各ファイルは空でなく、最大 20 MiB(20,971,520 バイト)である必要があります。リモート URL や他のアカウントのアップロードは拒否されます。
  • 読み取り可能な音声サンプルの合計時間は 10 秒以上、120 秒以下である必要があります。trimToMaxDuration のデフォルトは false です。合計が 120 秒を超えるサンプルを比例配分でトリミングするには、true に設定してください。
  • hasPermission は JSON のブール値 true で、すべてのサンプルに対する権限を確認する必要があります。“true” などの文字列値は拒否されます。
  • name は前後の空白を除去した後で 1–80 文字である必要があります。省略可能な language には、任意のサブタグを含む 2–3 文字の言語コードを、最大 35 文字で指定できます。
  • アカウントにつき全期間で 1 回限りのクローンプレビュー体験を使用します。このプレビューを作成しても、再利用可能な TTS 音声は保存されず、保存音声スロットも使用しません。
  • 新しいクローン候補は kind: clone で、有効期間は 24 時間です。再生は約 10 秒に制限されます。
  • レスポンスには、有効な未保存プレビューがすべて含まれます。voices_preview_get で再生 URL を更新し、有料プランでは voices_save_preview で選択した候補を保存してください。
  • language は、対応するスクリプトがある場合にプレビュー用スクリプトを選択します。アップロードしたサンプルの翻訳をリクエストするものではありません。
  • 読み上げ履歴とカスタム音声は認証済みアカウントに属します。チームの請求設定によって、他のメンバーの読み上げや音声へのアクセス権が付与されることはありません。

使用量

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

エラー