# ノード > POST /v1/ で、任意の Nodaro ノードを実行します。ノード、モデル、ピッカーの値を調べ、リファレンスや演出の ID でプロンプトを調整する方法も説明します。 Source: https://nodaro.ai/ja/docs/developers/api/nodes **ノードの実行**は、ワークフローを組まずに、Nodaro のノードを 1 つだけ直接呼び出します。`POST /v1/` に、ノードの設定をボディとして送信します。`generate-image` や `generate-video` から `text-to-speech` まで、すべての生成ノードがこの形に従っており、検出用のエンドポイントで、どのノード、モデル、設定が存在するかを調べられます。ほとんどのノードの実行は非同期です。レスポンスは `jobId` で、結果ができるまでポーリングします。 ## ノードを実行する ノードタイプのルートは、`POST /v1/` の後にそのタイプを付けたもので、ボディはノードの設定を JSON にしたものです。 ```http POST /v1/generate-image Authorization: Bearer ndr_… Content-Type: application/json { "prompt": "a lighthouse in a storm, oil painting", "provider": "nano-banana-pro", "aspectRatio": "3:4" } ``` 何が返ってくるかは、ノードによって異なります。 - **生成ノード**は、`200` とともに `{ "jobId": "…" }` を返します。処理はワーカー上で実行され、ステータスが `completed` になるまで `GET /v1/jobs/:id/status` でジョブをポーリングします。[ジョブ](https://nodaro.ai/docs/developers/api/jobs)を参照してください。 - **画像と動画の生成**では、`adjustments` が加わることがあります。これは、選んだモデルのためにサーバーが補正した設定の一覧です。`generate-video` では、`warnings` が加わることもあります。[パラメーターの補正](https://nodaro.ai/docs/developers/api/workflows#parameter-corrections)を参照してください。 - `combine-text` などの**インラインノード**は、`jobId` を返さずに、完全な結果をすぐに返します。 - `web-scrape` などの**スクレイパー**も、すぐに応答します。レスポンスには、履歴のための `jobId` と、データ自体の両方が含まれます。 生成は、開始時にクレジットを確保します。アカウントがその実行分をまかなえない場合、呼び出しは `402 insufficient_credits` を返します。 ### パスが長いノード 言語モデルを呼び出すテキストノードの多くは、同じ `POST /v1/` の規則に従います。`generate-script`、`image-critic`、`qa-check`、`describe-to-picker` です。それ以外の一部は、より長いパスで登録されています。 | ノードタイプ | ルート | | --- | --- | | `llm-chat` | `POST /v1/llm-chat/generate` | | `after-effects` | `POST /v1/after-effects/generate` | | `motion-graphics` | `POST /v1/motion-graphics/generate` | | `lottie-overlay` | `POST /v1/lottie-overlay/generate` | | `3d-title` | `POST /v1/3d-title/generate` | | `image-to-text` | `POST /v1/image-to-text/describe` | | `video-composer` | `POST /v1/scene-graph/generate` | SDK の `client.nodes.run(type, params)` は `/v1/` に POST します。そのため、これらのノードは `client.request('POST', '/v1/llm-chat/generate', { body })` のように呼び出します。 言語モデルのルートは、2 つの任意のフィールドを受け付けます。 - **`reasoningEffort`**：モデルによって、`none`、`low`、`medium`、`high`、`xhigh`、`max` のいずれかです。省略するか、そのモデルが対応していない段階を指定すると、モデル自体のデフォルトになります。`xhigh` と `max` は、クレジットのティアが 1 段階上がります。 - **`advancedMode: true`**：Gemini モデルのみです。リクエストはモデル開発元自身の API 上で実行されます。これは、`temperature`、`maxTokens`、推論の全範囲が効く唯一の経路です。`reasoningEffort` とは別に、クレジットのティアが 1 段階上がります。この経路がないモデルは、`400 advanced_mode_unsupported` を返します。 ## 例：画像を生成する ### ジョブを開始する **curl** ```bash 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 knight on a hill at dawn, cinematic", "provider": "nano-banana-pro", "aspectRatio": "16:9", "resolution": "2K" }' ``` ```json { "jobId": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10" } ``` **TypeScript SDK** ```ts const client = createClient({ baseUrl: 'https://app.nodaro.ai', auth: new StaticTokenAuth(process.env.NODARO_API_KEY!), }) const result = await client.nodes.run('generate-image', { prompt: 'a knight on a hill at dawn, cinematic', provider: 'nano-banana-pro', aspectRatio: '16:9', resolution: '2K', }) ``` **CLI** ```bash nodaro nodes run generate-image \ --param prompt="a knight on a hill at dawn, cinematic" \ --param provider=nano-banana-pro \ --param aspectRatio=16:9 \ --param resolution=2K ``` ### ジョブをポーリングする ステータスが `completed` か `failed` になるまで、2〜5 秒ごとにジョブのステータスを確認します。 ```bash curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \ -H "Authorization: Bearer $NODARO_API_KEY" | jq -r .data.status ``` ### 結果を読み取る 完了した画像のジョブは、画像の URL を `output_data.imageUrl` に持ちます。動画のジョブは `videoUrl` を、オーディオのジョブは `audioUrl` を使い、多くのジョブは `thumbnailUrl` も持ちます。 ```json { "data": { "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10", "status": "completed", "progress": 100, "output_data": { "imageUrl": "https://…/0f1a9c2e.png" }, "error_message": null } } ``` SDK と CLI は、代わりにポーリングを行えます。 **TypeScript SDK** ```ts const output = await client.nodes.runAndWait('generate-image', { prompt: 'a knight on a hill at dawn, cinematic', provider: 'nano-banana-pro', }) console.log(output.imageUrl) // Several candidates at once, in input order: const results = await client.nodes.runMany('generate-image', [ { prompt: 'a knight on a hill, sunrise' }, { prompt: 'a knight on a hill, golden hour' }, { prompt: 'a knight on a hill, blue hour' }, ]) for (const { jobId, output } of results) console.log(jobId, output.imageUrl) ``` **CLI** ```bash nodaro nodes run generate-image \ --param prompt="a knight on a hill at dawn, cinematic" \ --param provider=nano-banana-pro \ --watch --json | jq -r '.output_data.imageUrl' ``` `runAndWait` は、デフォルトで 2,000 ミリ秒ごとに、最大 15 分間ポーリングします。これは `pollMs` と `maxMs` で変更でき、`signal` に渡す `AbortSignal` で停止でき、`onProgress` で進行状況を追えます。`instanceof` で捕捉できる、型付きのエラーをスローします。 | エラー | 発生する場合 | | --- | --- | | `InsufficientCreditsError`、`StorageExceededError`、`JobBlockedError` | ジョブが開始される前に、実行が拒否された場合です。 | | `JobFailedError` | ジョブが `failed` か `cancelled` で終わった場合です。`jobId` とエラーメッセージを持ちます。 | | `JobTimeoutError` | `maxMs` が経過した場合です。ジョブはキャンセルされず、通常はそのまま完了します。後で `client.jobs.get(jobId)` を使って取得してください。 | | `JobAbortedError` | 自分の `signal` が発火した場合です。 | | `JobHeldError` | 結果をレビューするデプロイ環境で、ジョブが `pending_review` になった場合です。ジョブはキャンセルされません。後で確認してください。 | CLI では、配列やネストしたオブジェクトなどの複雑なボディを、`--params-file body.json` でファイルから渡します。同じキーについては、フラグの値がファイルの値を上書きします。`true`、`false`、`null`、数値は、テキストから変換されます。 ### 画像生成の設定 以下のフィールドは、`POST /v1/generate-image` でよく使う設定です。各設定がエディターで何を行うかは、[**画像生成**（Generate Image）](https://nodaro.ai/docs/nodes/image/generate-image)を、各モデルが対応している内容は、[画像モデル](https://nodaro.ai/docs/models/image)を参照してください。 マスクを使った編集やリファインの料金は、そのモデルでの新規生成と同じです。 ## 動画を生成する 動画を作るルートは 2 つあります。`POST /v1/generate-video` は、画像からアニメーションを作ります。`imageUrl` の開始フレーム、任意で `endFrameUrl` の最後のフレーム、または、対応しているモデルではリファレンスだけです。`POST /v1/text-to-video` は、プロンプトだけからクリップを作るので、`prompt` が必須です。`provider` を省略すると、プラットフォームのデフォルトの動画モデルが使われます。 ```json { "imageUrl": "https://…/frame.png", "provider": "seedance-2", "prompt": "she turns toward the window", "duration": 8, "resolution": "720p", "direction": { "cameraMotion": "dolly-in", "timeOfDay": "dawn" } } ``` レスポンスは `{ "jobId": "…" }` で、当てはまる場合は `warnings` と `adjustments` も含まれます。完了したジョブは `output_data.videoUrl` を持ちます。 モデルによって異なる規則が、いくつかあります。 - **Seedance 2 系列では、`resolution` と `aspectRatio` がそのまま渡されます**。モデルが対応していない値は、拒否されずに無視されます。`4k` と `adaptive` に対応しているのは、[Seedance 2](https://nodaro.ai/docs/models/video/seedance-2) だけです。[Seedance 2.5](https://nodaro.ai/docs/models/video/seedance-2-5) は、1 回の呼び出しで最大 30 秒を作れます。開始フレームがある場合、常にそのフレームのアスペクト比でレンダリングします。 - **[MiniMax Hailuo 3](https://nodaro.ai/docs/models/video/minimax-h3) の `resolution` は `2K` または `768P`** で、まさにこの表記で指定します。送信する値は、`GET /v1/nodes/:type` の `providerResolutionWire` に一覧表示されます。 - Seedance 2 と MiniMax Hailuo 3 では、**フレームとリファレンスを組み合わせられます**。開始または終了フレームと一緒にリファレンスを送信すると、そのフレームは固定の始点や終点ではなく、プロンプト内の番号付きリファレンスになります。[Wan 3.0](https://nodaro.ai/docs/models/video/wan-3-0) では両方を送れないため、代わりにフレームがリファレンスの一覧の末尾に追加され、呼び出しはそのまま成功します。 - **リファレンス動画は、料金が高くなります。**課金対象にしているモデルでは、リファレンスクリップの料金は、そのクリップ自体の長さと出力の長さを合わせて決まります。そのため、元のクリップが長いほど、確保されるクレジットも増えます。Wan 3.0 は、出力の秒数だけを課金します。 各モデルの長さ、解像度、クレジット料金については、[動画モデル](https://nodaro.ai/docs/models/video)を読むか、`GET /v1/models` を呼び出してください。 ## リファレンスを使う リファレンスは、モデルに合わせてほしい画像、そして動画ではクリップとオーディオでもあります。フラットな URL のリストとして送ることも、ルートが番号を振り、ラベルを付けてプロンプトに書き込む**構造化されたリファレンス**として送ることもできます。これは、エディターが接続されたノードに対して行うのと同じです。 ### 構造化されたリファレンス `connectedReferences` は、`POST /v1/generate-image`、`POST /v1/generate-video`、`POST /v1/text-to-video`、`POST /v1/extend-video` で受け付けられます。各エントリーは、1 枚の画像を表します。 動画のルートでは、これらのエントリーを番号付きのリファレンスに変換します。 - **メンションしなかったリファレンスは、すべて添付されます。**その URL は重複を除いてリファレンスの一覧に加わり、`@image_1 (reference):