Skip to main content
POST
ご自身が所有する参照画像アップロードの署名付き PUT URL を取得します。8 MiB の画像は最大 2 パートです。upload_complete に使用するため、各 PUT で返された ETag を保存してください。

認証と権限

string
必須
このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP でのみ使用でき、この REST エンドポイントでは使用できません。
必要な権限: images: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
必須
このドメインの upload_initialize アクションが返した uploadId。形式: “uuid”. パターン: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.
array
必須
値のリスト。要素の構造は完全な入力スキーマを参照してください。最小要素数: 1. 最大要素数: 2.
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。

冪等性

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

リクエスト例

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

レスポンス

初回実行が成功すると、操作結果を data に格納して HTTP 200 を返します。同じリクエストを再送した場合は、代わりに保存済みリクエストの状態を返すことがあります。例はサポートされるレスポンスの一例であり、すべての任意フィールドを示すものではありません。 リクエストした重複のないパート番号ごとに1つの、一時的な署名付きPUT URLの配列。レスポンスには画像バイト列、ETags、パートごとのサイズフィールドは含まれません。

結果フィールド

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

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

操作の注意事項

  • images:write が必要です。追加のアップロードスコープは不要です。
  • uploadId は initialize が返す UUID です。partNumbers には 1 から 2 の整数を 1–2 件指定し、各パートはそのセッションの申告 fileSize に対して存在している必要があります。要求したパート番号が重複する場合、URL は1つにまとめられます。
  • 返された各 URL に、パートの生のバイナリデータを PUT します。Content-Length は署名対象であり、min(partSize, fileSize - (partNumber - 1) × partSize) と完全に一致する必要があります。7 MiB の例では、パート 1 は 5,242,880 バイト、パート 2 は 2,097,152 バイトです。署名付き URL に JSON、multipart/form-data、base64 を送信しないでください。
  • 成功した各 PUT の ETag レスポンスヘッダーを保存し、images_upload_complete にその値を送信してください。署名付きURLは、非公開の一時アップロード権限として扱ってください。
  • 署名、完了、中止を行えるのは、接続ユーザーが所有するアップロードだけです。別のアップロード系統で作成されたセッションでも、これらのエイリアスが受け付けるのは、最大 8 MiB の JPG、PNG、WebP セッションだけです。
  • 本番環境のアップロードセッションは24時間後に期限切れになります。署名付きパートURLの有効期間は1時間です。完了と中止はアクティブなセッションを削除するため、その後の sign-parts と complete は Upload not found を返します。どちらのレスポンスにも expiresAt フィールドは含まれません。
  • UUID v4 の requestId、または HTTP の Idempotency-Key ヘッダーを使用し、再試行時は同一の入力で再利用してください。連携レイヤーは各変更を記録し、再実行せずに記録済みの状態または結果を返します。failed または interrupted のリクエストは、自動的には再試行されません。
  • 有効期限の1時間が過ぎてもセッションが有効な場合、新しい requestId で sign-parts を呼び出すと新しい URL を取得できます。同じ requestId で再試行すると、古い URL を含む保存済み結果が返されます。

使用量

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

エラー