Skip to main content
POST
接続先アカウントの画像を生成します。Web アプリと同じメディア利用枠と保護機能が適用されます。返された generationId を保存し、images_download で画像を取得してください。同じリクエストを再試行するときは requestId を再利用します。

認証と権限

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
必須
テキスト値。最小文字数: 10. 最大文字数: 1200.
string
テキスト値。許容値: “square”, “landscape”, “portrait”. デフォルト値: “square”.
string
uploads/{yourUserId}/ 配下にアップロードしたJPG、PNG、WebPのオブジェクトキー。外部URLは使用できません。最小文字数: 1. 最大文字数: 512.
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。

冪等性

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

リクエスト例

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

レスポンス

この操作は実行中に HTTP 202 を返します。requestId を保存し、その識別子と元の操作名を指定して action_request_get をポーリングしてください。ポーリングの状態は running、completed、failed、interrupted です。完了した結果が別のメディアジョブを示す場合は、その操作に対応するステータスまたは出力取得アクションで処理を続けてください。 画像生成の完了後にハンドラーが返す最終生成メタデータ。画像のバイナリデータ、previewDataUrl、ダウンロード URL は含まれません。

結果フィールド

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

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

操作の注意事項

  • images:write が必要です。プロンプトは前後の空白を除去した後で10~1200文字である必要があり、生成前に正規化もされます。aspectRatio のデフォルトは square で、landscape または portrait も指定できます。referenceImageKey は最大1つです。
  • これは長時間実行アクションです。最初の API/MCP レスポンスは通常 running を返します。ここに示す最終結果を取得するには、operation を images_generate にして、同じ requestId で action_request_get をポーリングしてください。
  • アカウントの通常の 1 日あたりの画像生成利用枠を使用します。アカウントで生成した画像は作成から 7 日後に有効期限が切れます。expiresAt より前に結果をダウンロードしてください。
  • 認証情報がチームのコンテキストで接続されている場合も、このアクションは接続ユーザー自身の作成物とアップロードを使用します。
  • 参照キーは uploads/{yourUserId}/ 配下の完了済みアップロードを指し、末尾が .jpg、.jpeg、.png、.webp のいずれかである必要があります。リモート URL、他のユーザーのキー、パストラバーサルのセグメント、バックスラッシュ、パーセントエスケープ、クエリ文字列、フラグメント、制御文字は拒否されます。
  • 各参照画像は空でなく、最大 8 MiB(8,388,608 バイト)で、拡張子が示す画像形式としてデコードでき、縦横それぞれ 128–4096 ピクセルである必要があります。デコード後の総ピクセル数にも上限があります。アップロードした参照画像は再利用できます。これらの生成アクションは、アップロード済みファイルを消費も削除もしません。
  • UUID v4 の requestId、または HTTP の Idempotency-Key ヘッダーを使用し、再試行時は同一の入力で再利用してください。連携レイヤーは各変更を記録し、再実行せずに記録済みの状態または結果を返します。failed または interrupted のリクエストは、自動的には再試行されません。
  • このユーザーが一度に生成できる画像は1枚だけです。生成状態は images_list と images_get、PNG のバイトデータは images_download で取得してください。生成の識別子は不透明な文字列です。requestId に置き換えないでください。

使用量

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

エラー