# REST API の概要

> Nodaro REST API は、HTTPS 上の JSON と Bearer トークンで、ワークフローや単体のノードの実行、ジョブのポーリング、メディアのアップロード、アセットの管理を行います。

Source: https://nodaro.ai/ja/docs/developers/api

**Nodaro REST API** は、Nodaro を HTTP で操作するためのインターフェースです。ワークフローや単体のノードを実行し、そのジョブのステータスを返し、メディアを保存し、キャラクター、プリセット、ワークスペースを管理します。リクエストとレスポンスは HTTPS でやり取りする JSON で、すべてのリクエストに Bearer トークンを付けます。Nodaro Cloud とセルフホスティング環境のどちらでも同じ API が使われ、[TypeScript SDK](https://nodaro.ai/docs/developers/sdk) と [CLI](https://nodaro.ai/docs/developers/cli) は、この API を薄くラップしたクライアントです。

## ベース URL
| Nodaro の稼働環境 | ベース URL |
| --- | --- |
| Nodaro Cloud | `https://app.nodaro.ai` |
| セルフホスティング環境 | その環境自体のアドレス（たとえば、デフォルト設定でインストールした Community エディションでは `http://localhost:3000`） |

すべてのパスは `/v1/` で始まり、たとえば `https://app.nodaro.ai/v1/nodes` のようになります。クレジットや組織など、Nodaro Cloud にしかないエンドポイントもあり、それらはほかのエディションでは `404` を返します。エンドポイントに制限がある場合は、各ページにそのことを記載しています。

## 認証
すべてのリクエストで `Authorization: Bearer <token>` を送ります。自分のアカウントで使う場合は、**設定 › APIトークン**で作成した個人用 API トークン（`ndr_…`）を使います。自分のプロダクトがほかの Nodaro ユーザーの代わりに操作する場合は OAuth アクセストークン（`ndr_app_…`）を、Community エディションの環境ではセッションの JWT を使います。`GET /v1/nodes` や `GET /v1/models` など、一部のディスカバリー用エンドポイントは、トークンなしで呼び出せます。トークンの作成方法は、[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。

## 最初の API 呼び出し
この例では、1 つのノードで画像を生成し、その結果を読み取ります。生成は非同期です。最初の呼び出しはジョブ ID を返すので、ジョブが完了するまでポーリングします。

**curl**

```bash
export NODARO_API_KEY="ndr_..."

# 1. Start the job
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"prompt": "a snow leopard on a mountain ridge at dawn",
"provider": "nano-banana-pro",
"aspectRatio": "16:9"
}'
# {"jobId":"0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10"}

# 2. Poll the job until its status is "completed"
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

```json
{
"data": {
"id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
"status": "completed",
"progress": 100,
"output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
"error_message": null
}
}
```

**TypeScript SDK**

```ts

const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

// Starts the job and polls it until it finishes.
const output = await client.nodes.runAndWait('generate-image', {
prompt: 'a snow leopard on a mountain ridge at dawn',
provider: 'nano-banana-pro',
aspectRatio: '16:9',
})
console.log(output.imageUrl)
```

**CLI**

```bash
nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge at dawn" \
  --param provider=nano-banana-pro \
  --param aspectRatio=16:9 \
  --watch --json | jq -r '.output_data.imageUrl'
```

どの生成ノードも、同じ手順で実行できます。ノードの設定を付けて `POST /v1/<node-type>` を呼び出し、ジョブをポーリングします。[単体のノードを実行する](https://nodaro.ai/docs/developers/api/nodes)を参照してください。

## リクエストとレスポンスの規約
- **JSON で送り、JSON で受け取ります**。リクエストボディは、`Content-Type: application/json` を付けて JSON で送ります。例外はファイルのアップロードで、`multipart/form-data` を使います。
- **ID は UUID です**。形式が正しくない ID には、`400 validation_error` が返ります。
- **ほとんどのレスポンスは `data` で包まれています**。読み取りは `{ "data": … }` を返し、削除やキャンセルは `{ "success": true }` を返します。`/v1/api/` 以下にある従来のワークフロー用エンドポイントは、ペイロードをそのまま返します。
- **生成はジョブ ID を返します**。`POST /v1/<node-type>` は `{ "jobId": "…" }` を返し、`adjustments` や `warnings` が一緒に付くこともあります。
- **一覧のページネーションにはカーソルを使います**。一覧はカーソルを返します。通常は `nextCursor` で、`GET /v1/jobs` では `next` です。次のページを取得するには、その値を `?cursor=` で渡します。カーソルが `null` なら、それ以上の行はありません。カーソルは不透明な値なので、解析したり自分で組み立てたりしないでください。
- **フィールド名の形式は 2 種類あります**。ジョブのオブジェクトは、`output_data` や `created_at` のようなスネークケース（snake_case）です。ワークフロー、実行、その他のほとんどのリソースは、キャメルケース（camelCase）です。
- **レスポンスのフィールドは増えていきます**。新しいフィールドは随時追加されます。知らないフィールドがあってもエラーにせず、無視してください。
- **エラーの形式は 1 つです**。失敗した呼び出しは、HTTP ステータスと `{ "error": { "code": "…", "message": "…" } }` を返します。処理の分岐には `code` を使います。[エラー](https://nodaro.ai/docs/developers/api/errors)を参照してください。

次の 2 つの任意のヘッダーで、リクエストの扱いを変えられます。

| ヘッダー | 役割 |
| --- | --- |
| `X-Nodaro-Workspace` | 組織内の 1 つのワークスペースで操作します。一覧をどのワークスペースから読み取るか、作成したものをどこに置くかが、このヘッダーで決まります。[ワークスペース](https://nodaro.ai/docs/developers/api/workspaces)を参照してください。 |
| `X-Nodaro-Client` | ジョブを作成したクライアントを記録します。値は `sdk/<version>`、`cli/<version>`、`extension/<name>` のいずれかです。[クライアントを識別する](https://nodaro.ai/docs/developers/api/authentication#identify-your-client)を参照してください。 |

## 同期と非同期
Nodaro の処理の多くは数秒から数分かかるため、API は非同期です。生成のルートはすぐに `jobId` を返し、ワークフローの実行は `executionId` とともに `202 Accepted` を返します。その後、最終ステータスになるまで、2〜5 秒ごとに[ジョブ](https://nodaro.ai/docs/developers/api/jobs)または[実行](https://nodaro.ai/docs/developers/api/executions)をポーリングします。1 分以内に終わる見込みのワークフローでは、`POST /v1/api/run?wait=true` が最大 600 秒間接続を保持し、結果を返します。インラインで処理されるテキストノード、無料のメディア処理、構造化出力の LLM 呼び出しなど、同期的に応答するルートもいくつかあります。詳しくは、[同期と非同期](https://nodaro.ai/docs/developers/api/workflows#sync-or-async)を参照してください。

## 分野別のエンドポイント
### 実行する
| ページ | 内容 | 主なエンドポイント |
| --- | --- | --- |
| [ワークフロー](https://nodaro.ai/docs/developers/api/workflows) | 保存したワークフローの実行（入力値の指定の有無を問わず）と、ワークフローの管理 | `POST /v1/workflows/:id/run`、`POST /v1/api/run`、`GET /v1/api/schema` |
| [ノード](https://nodaro.ai/docs/developers/api/nodes) | ワークフローを使わない単体のノードの実行と、利用できるノード、モデル、ピッカーの確認 | `POST /v1/<node-type>`、`GET /v1/nodes`、`GET /v1/models` |
| [ジョブ](https://nodaro.ai/docs/developers/api/jobs) | ジョブのステータスと結果、一括ポーリング、キャンセル、**動画生成 Pro**（Generate Video Pro）の実行の制御 | `GET /v1/jobs/:id/status`、`POST /v1/jobs/batch-status` |
| [実行](https://nodaro.ai/docs/developers/api/executions) | ワークフローの実行のステータスと履歴 | `GET /v1/workflow-executions/:id`、`GET /v1/workflows/:id/executions` |
| [アップロード](https://nodaro.ai/docs/developers/api/uploads) | 画像、動画、オーディオのアップロードと、URL の内容のストレージへのコピー | `POST /v1/upload`、`POST /v1/save-to-storage` |
| [Webhook](https://nodaro.ai/docs/developers/api/webhooks) | HTTP 呼び出しやスケジュールによるワークフローの開始と、結果の外部への送信 | `POST /v1/webhooks/:token`、`POST /v1/workflow-triggers` |

### リソース
| ページ | 内容 | 主なエンドポイント |
| --- | --- | --- |
| [キャラクター](https://nodaro.ai/docs/developers/api/characters) | キャラクター、ポートレートの候補、表情、ポーズ、モーション | `/v1/characters`、`POST /v1/generate-character` |
| [オブジェクト](https://nodaro.ai/docs/developers/api/objects) | 小道具、製品、乗り物と、そのメイン画像とバリエーション | `/v1/objects`、`POST /v1/generate-object` |
| [ロケーション](https://nodaro.ai/docs/developers/api/locations) | 場所と、そのメイン画像とバリエーション | `/v1/locations`、`POST /v1/generate-location` |
| [クリーチャー](https://nodaro.ai/docs/developers/api/creatures) | クリーチャーと、そのメイン画像とバリエーション | `/v1/creatures` |
| [プリセット](https://nodaro.ai/docs/developers/api/presets) | 自分のノードプリセットと、組み込みのカタログ（読み取り専用） | `GET /v1/node-presets`、`GET /v1/node-presets/factory` |
| [コミュニティ](https://nodaro.ai/docs/developers/api/community) | 共有されたキャラクター、ロケーション、オブジェクトの閲覧と複製 | `GET /v1/community/browse` |
| [パイプライン](https://nodaro.ai/docs/developers/api/pipelines) | **ストーリー → 動画**（Story → Video）のパイプライン | `POST /v1/pipelines/:id/branch` |
| [プロンプトウィザード](https://nodaro.ai/docs/developers/api/prompt-wizard) | 生成ノード用のプロンプトの改善 | `POST /v1/prompt-helper/wizard` |
| [Recast](https://nodaro.ai/docs/developers/api/recast) | 分析済みの動画を、自分のキャストで再生成 | `POST /v1/recast` |
| [スタジオプロダクション](https://nodaro.ai/docs/developers/api/studio-productions) | ショット単位で組み立てるプロダクション | `/v1/studio/productions` |
| [音声とメディア](https://nodaro.ai/docs/developers/api/voice-and-media) | ボイス、ボイスチェンジ、吹き替え、メディアのインポート、オーディオツール | `/v1/voices`、`/v1/download-video`、`/v1/transcribe` |
| [キャラクター学習](https://nodaro.ai/docs/developers/api/character-training) | 1 人のキャラクターでのモデルの学習 | `POST /v1/characters/:id/train` |
| [3D シーン](https://nodaro.ai/docs/developers/api/3d-scenes) | 編集できる 3D シーンと、**3D レンダリング Pro**（3D Render Pro） | `POST /v1/3d-scene/generate`、`POST /v1/pro-3d-render` |

### アカウント
| ページ | 内容 | 主なエンドポイント |
| --- | --- | --- |
| [ワークスペースと組織](https://nodaro.ai/docs/developers/api/workspaces) | ワークスペースでの操作、組織、メンバー、招待、使用量 | `/v1/orgs`、`/v1/workspaces` |
| [クレジット](https://nodaro.ai/docs/developers/api/credits) | 残高、取引履歴、料金の確認 | `GET /v1/credits/balance`、`GET /v1/credits/transactions` |

### リファレンス
| ページ | 内容 |
| --- | --- |
| [エラー](https://nodaro.ai/docs/developers/api/errors) | エラーエンベロープ、すべてのエラーコード、ジョブの失敗のヒント |
| [レート制限](https://nodaro.ai/docs/developers/api/rate-limits) | トークンごとの制限、ルートごとの制限、`429` への対処方法 |
| [OpenAPI 仕様](https://nodaro.ai/docs/developers/api/openapi) | `GET /v1/openapi.json` で取得できる機械可読な仕様と、ほかの言語向けのクライアント |

## 制限とエラー
個人用 API トークンでは、ワークフローの実行と一覧取得のエンドポイントに、デフォルトで 1 分あたり 30 リクエスト（最大 120 まで設定可能）を送れます。また、一部のルートには独自の制限があります。ステータスのポーリングは、トークンの制限にカウントされません。`429` は、ペースを落とし、バックオフしながら再試行する必要があることを示します。`4xx` は、再試行する前にリクエストを修正する必要があることを示し、`5xx` は通常、一時的なエラーです。[レート制限](https://nodaro.ai/docs/developers/api/rate-limits)と[エラー](https://nodaro.ai/docs/developers/api/errors)を参照してください。

## 言語別のクライアント
- **TypeScript と JavaScript**：`npm install @nodaro/sdk` でインストールします。[SDK](https://nodaro.ai/docs/developers/sdk) は、これらのエンドポイントを、型、型付きのエラー、ポーリング用のヘルパーとともにラップしています。
- **ターミナルと CI**：`npm install -g @nodaro/cli` でインストールします。[CLI](https://nodaro.ai/docs/developers/cli) は、ワークフロー、アプリ、単体のノードを実行でき、`--watch` と `--json` に対応しています。
- **その他の言語**：[OpenAPI 仕様](https://nodaro.ai/docs/developers/api/openapi)からクライアントを生成するか、通常の HTTPS リクエストを送ります。
- **AI アシスタント**：コードを書く代わりに、[MCP サーバー](https://nodaro.ai/docs/mcp)に接続します。

## Frequently asked questions

### Nodaro API のベース URL は何ですか？

Nodaro Cloud では https://app.nodaro.ai です。すべてのパスは /v1/ で始まり、たとえば https://app.nodaro.ai/v1/nodes のようになります。セルフホスティング環境では、その環境のアドレスを使ってください。

### Nodaro API は同期型ですか、非同期型ですか？

ほとんどは非同期です。生成はジョブ ID を、ワークフローの実行は実行 ID を返すので、処理が終わるまでそれらをポーリングします。1 分以内に終わるワークフローでは、代わりに POST /v1/api/run?wait=true で接続を保持することもできます。

### Nodaro API は、どのプログラミング言語で使えますか？

JSON で HTTPS リクエストを送れる言語なら、どれでも使えます。TypeScript と JavaScript には @nodaro/sdk パッケージがあります。Go、Rust、Python などでは、OpenAPI 3.1 の仕様から型付きのクライアントを生成できます。

### Nodaro API の利用にクレジットはかかりますか？

生成にはかかります。Nodaro Cloud では、エディターと同じく、生成のたびにモデルの料金分のクレジットを消費します。セルフホスティングした Community エディションにはクレジットの仕組みがなく、モデルのプロバイダーに直接支払います。

### API を使うには、サブスクリプションが必要ですか？

いいえ。Nodaro Cloud では、どのクレジットパックを購入しても従量課金が有効になり、従量課金のクレジットは API、SDK、CLI、MCP で使えます。Web エディターを使うには、サブスクリプションが必要です。