> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 実行と料金を管理する

> 非同期実行、冪等な再試行、料金予約、精算、成果物の取得方法を説明します。

## 概要

このページでは、有料ツールの見積もり、料金予約、非同期実行、精算、成果物の取得までの流れを説明します。長時間かかる処理は、HTTP接続を開いたまま待たず、実行IDで状態を追跡します。

## 実行と課金の流れを理解する

`POST /tools/quote`は、現在の入力に対する料金バージョン、最小料金、最大予約額を返します。見積もり自体は無料で、外部サービスへの処理も料金予約も行いません。

実行するときは、見積もりと同じ`tool`と`arguments`に次の2項目を追加します。

* `priceVersion` — 見積もりで返された料金バージョン
* `maximumChargeMicros` — 見積もりで返された最大予約額

実行時に料金が変わった場合や、指定した上限が不足する場合は、処理を開始せずリクエストを拒否します。新しい見積もりを取得して、内容を改めて確認してください。

## 料金を予約して精算する

有料処理の受付時に、最大予約額を前払いUSD残高から一時的に確保します。処理完了後、実際の利用額を確定し、使わなかった予約分を残高へ戻します。

| 項目               | 意味                                 |
| ---------------- | ---------------------------------- |
| `reservedMicros` | 受付時に確保した最大額。完了後も当初の値を示します。         |
| `chargedMicros`  | 完了または失敗後に確定した請求額。処理中の`0`は未精算を表します。 |
| `currency`       | `usd`。1 USDは1,000,000 microsです。    |

失敗またはキャンセルでも、すでに外部処理の原価が発生している場合は、その実額が精算されます。最大予約額を超えて自動請求されることはありません。

## 実行状態を確認する

受付時にはHTTP 202と実行IDが返ります。レスポンスの`Retry-After: 5`を目安に、5秒以上の間隔で同じ実行IDを確認します。

| 状態             | 意味            | 次の対応                          |
| -------------- | ------------- | ----------------------------- |
| `queued`       | 実行待ち          | 5秒以上待って再確認する                  |
| `running`      | 処理中           | 同じ実行IDを再確認する                  |
| `waiting`      | 外部処理の結果待ち     | 同じ実行IDを再確認する                  |
| `succeeded`    | 成功し、精算済み      | `output`と`chargedMicros`を確認する |
| `failed`       | 失敗し、発生済み原価を精算 | `errorCode`と確定額を確認する          |
| `cancelled`    | キャンセル処理が完了    | 確定額を確認する                      |
| `needs_review` | 結果または原価の確認が必要 | 再実行せず、実行IDを添えてサポートへ連絡する       |

## 冪等キーで二重実行を防ぐ

冪等キーは、「同じ依頼を誤って複数回送っても、別の実行として重複させない」ための識別子です。有料の`POST /tools/{tool}`では、`Idempotency-Key`ヘッダーが必須です。

キーは8〜128文字で、英数字と`.`、`_`、`:`、`-`を使用できます。1つの論理リクエストにつき1つ生成し、実行IDと一緒に保存してください。

* 同じAPIキー、同じ本文、同じ冪等キーを再送すると、同じ実行が返ります。
* 同じ冪等キーで本文やAPIキーを変えると、HTTP 409になります。
* 通信が切れた場合は、本文や冪等キーを変えずに再送します。
* `needs_review`になった処理を新しい冪等キーで送ると、別の有料実行になります。

<Warning>
  応答が届かなかったことは、実行が受け付けられなかった証明にはなりません。結果が不明なときに新しい冪等キーを作らないでください。
</Warning>

## 実行をキャンセルする

`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キーを付けないでください。

## 関連ページ

初回実行とエンドポイントの詳細は、次のページで確認できます。

* [使い始める](/ja/developers/api/getting-started)
* [仕様を確認する](/ja/developers/api/reference)