概要
このページでは、有料ツールの見積もり、料金予約、非同期実行、精算、成果物の取得までの流れを説明します。長時間かかる処理は、HTTP接続を開いたまま待たず、実行IDで状態を追跡します。実行と課金の流れを理解する
POST /tools/quoteは、現在の入力に対する料金バージョン、最小料金、最大予約額を返します。見積もり自体は無料で、外部サービスへの処理も料金予約も行いません。
実行するときは、見積もりと同じtoolとargumentsに次の2項目を追加します。
priceVersion— 見積もりで返された料金バージョンmaximumChargeMicros— 見積もりで返された最大予約額
料金を予約して精算する
有料処理の受付時に、最大予約額を前払いUSD残高から一時的に確保します。処理完了後、実際の利用額を確定し、使わなかった予約分を残高へ戻します。
失敗またはキャンセルでも、すでに外部処理の原価が発生している場合は、その実額が精算されます。最大予約額を超えて自動請求されることはありません。
実行状態を確認する
受付時にはHTTP 202と実行IDが返ります。レスポンスのRetry-After: 5を目安に、5秒以上の間隔で同じ実行IDを確認します。
冪等キーで二重実行を防ぐ
冪等キーは、「同じ依頼を誤って複数回送っても、別の実行として重複させない」ための識別子です。有料のPOST /tools/{tool}では、Idempotency-Keyヘッダーが必須です。
キーは8〜128文字で、英数字と.、_、:、-を使用できます。1つの論理リクエストにつき1つ生成し、実行IDと一緒に保存してください。
- 同じAPIキー、同じ本文、同じ冪等キーを再送すると、同じ実行が返ります。
- 同じ冪等キーで本文やAPIキーを変えると、HTTP 409になります。
- 通信が切れた場合は、本文や冪等キーを変えずに再送します。
needs_reviewになった処理を新しい冪等キーで送ると、別の有料実行になります。
実行をキャンセルする
POST /tools/executions/{id}/cancelは、未開始の処理を停止する要求です。実行を作成したキー、またはプロジェクトのADMINが操作できます。
すでに外部処理が始まっている場合、キャンセル要求だけで処理や料金を取り消せないことがあります。cancelRequestedと最終的なstatus、chargedMicrosを確認してください。
成果物を取得する
画像、音声、動画などの生成結果は、output.artifactsにファイルID、形式、サイズ、ハッシュ、取得期限として返ります。ファイル本体や恒久URLは実行結果へ含まれません。
GET /tools/executions/{id}/artifacts/{artifactId}/downloadを呼ぶと、最大5分間有効なダウンロードURLが返ります。保存ファイルの取得期限は30日です。
ダウンロードURLは一時的であっても私的データへのアクセス情報です。ログや公開ページへ記録せず、URLへDeveloper PlatformのAPIキーを付けないでください。