> ## 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.

# 仕様を確認する

> Base URL、エンドポイント、レスポンス、エラー、利用上限をまとめて確認できます。

## 概要

このページでは、Developer Platform APIに共通する接続情報、エンドポイント、レスポンス形式、エラー、利用上限をまとめます。各ツール固有の入力形式と現在の料金は、`GET /tools`で取得してください。

## Base URLと共通ヘッダーを確認する

すべてのパスは、次のBase URLへ追加します。

```text theme={null}
https://api.noimosai.com/noimosToolBridge
```

認証にはDeveloper PlatformのAPIキーを使います。JSON本文を送る場合はContent-Typeも指定します。

```http theme={null}
Authorization: Bearer nmp_...
Content-Type: application/json
```

有料実行では、次のヘッダーも必須です。

```http theme={null}
Idempotency-Key: request-unique-id
```

## エンドポイントを確認する

公開APIで利用する主なエンドポイントは次のとおりです。

| メソッドとパス                                                      | 必要な権限             | 用途                           |
| ------------------------------------------------------------ | ----------------- | ---------------------------- |
| `GET /tools/project`                                         | `project:read`    | キーが属する組織とプロジェクトを確認する         |
| `GET /tools/usage`                                           | `usage:read`      | 当月UTCの確定済みリクエスト数とUSD利用料を確認する |
| `GET /tools`                                                 | `tools:read`      | ツール、入力形式、例、提供状態、料金を取得する      |
| `POST /tools/quote`                                          | `tools:read`      | 入力に対する最大予約額を無料で見積もる          |
| `POST /tools/upload`                                         | `tools:execute`   | 明示した素材をプロジェクト内へ非公開保存する       |
| `POST /tools/{tool}`                                         | `tools:execute`   | 料金上限を予約し、有料処理を登録する           |
| `GET /tools/executions`                                      | `executions:read` | プロジェクトの実行一覧を取得する             |
| `GET /tools/executions/{id}`                                 | `executions:read` | 実行状態、結果、確定額を取得する             |
| `POST /tools/executions/{id}/cancel`                         | `tools:execute`   | 実行のキャンセルを要求する                |
| `GET /tools/executions/{id}/artifacts/{artifactId}/download` | `executions:read` | 生成ファイルの期限付きURLを取得する          |

`GET /tools/executions`では、`limit`、`before`、`status`、`tool`で一覧を絞り込めます。`limit`は1〜100で、既定値は20です。

## ツールカタログを確認する

`GET /tools`の`data`には、カタログ全体の料金バージョン、通貨、実行可否、ツール一覧が含まれます。

各ツールでは、次の情報を確認できます。

* `name` — 実行URLと本文に指定するツール名
* `description`と`category` — 用途と分類
* `available` — 必要な外部サービスが設定され、提供可能か
* `inputSchema`と`example` — 入力のJSON Schemaと例
* `models` — 選択できるモデルとモデル別の入力例、提供状態、料金説明
* `price` — 最小料金、課金単位、料金説明

`available: true`だけで実行できるとは限りません。カタログ全体の`executionEnabled`、キーの権限、前払い残高、月間上限も適用されます。

## レスポンス形式を確認する

成功レスポンスの本体は、原則として`data`に入ります。

```json theme={null}
{
  "data": {}
}
```

エラーは`error`に状態とメッセージが入ります。

```json theme={null}
{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required"
  }
}
```

すべてのレスポンスには`Cache-Control: no-store`が設定されます。APIキー、結果、期限付きURLを共有キャッシュへ保存しないでください。

## エラーへ対応する

受け取ったステータスに応じて、再送前に原因を確認します。

| HTTP  | 主な意味                   | 対応                             |
| ----- | ---------------------- | ------------------------------ |
| `200` | 取得成功、または完了済みの同一実行      | `data`を処理する                    |
| `202` | 非同期処理を受け付けた            | 実行IDを保存し、5秒以上待って確認する           |
| `400` | 入力、見積もり、状態が不正          | カタログと見積もりを確認する                 |
| `401` | 認証できない                 | Authorizationヘッダー、期限、失効状態を確認する |
| `403` | 権限がない                  | キーの権限とプロジェクト権限を確認する            |
| `404` | エンドポイント、操作、成果物が利用できない  | パス、提供状態、取得期限を確認する              |
| `409` | 冪等キーが別のリクエストで使われている    | 元の本文とキーを確認し、新しい実行を安易に作らない      |
| `429` | リクエスト上限、残高、月間上限に到達     | 該当する上限と残高を確認する                 |
| `503` | 実行または外部サービスを一時的に利用できない | 有料実行の受付有無を確認してから再試行する          |

## 利用上限を確認する

クライアント実装では、次の上限を考慮してください。

| 対象             | 上限                   |
| -------------- | -------------------- |
| 通常のJSONリクエスト   | UTF-8で64 KiB         |
| アップロードできる実ファイル | 12 MiB               |
| アップロード対応形式     | JPEG、PNG、WAV、MP3、MP4 |
| リクエスト数         | APIキーごとに固定1分間で120回   |
| 状態確認の間隔        | 5秒以上                 |
| 1回の実行ステップ数     | 最大20                 |
| 生成ファイルの保存期間    | 30日                  |
| ダウンロードURLの有効期間 | 最大5分                 |

リクエスト数には、カタログ、見積もり、アップロード、実行、状態確認、再送も含まれます。429を避けるため、状態確認を必要以上に短い間隔で繰り返さないでください。

## 素材をアップロードする

ローカルの画像・音声・動画を使う場合は、`POST /tools/upload`へMIME形式とBase64データを送ります。

```json theme={null}
{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}
```

成功すると`fileId`として使える`id`、形式、サイズ、SHA-256、取得期限が返ります。ツール固有の`source`などへ、カタログが示す形式で指定してください。同じプロジェクト・同じ内容では同じIDが返り、保存期限は初回アップロードから延長されません。

## 関連ページ

認証と実行フローは、次のページで確認できます。

* [認証する](/ja/developers/api/authentication)
* [実行と料金を管理する](/ja/developers/api/execution-and-billing)
* [Developer Platformのドキュメント](https://platform.noimosai.com/docs)