NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

REST API の概要

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

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

ベース URL

Nodaro の稼働環境ベース URL
Nodaro Cloudhttps://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 など、一部のディスカバリー用エンドポイントは、トークンなしで呼び出せます。トークンの作成方法は、認証を参照してください。

最初の API 呼び出し

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

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"
{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null
  }
}
import { createClient, StaticTokenAuth } from '@nodaro/sdk'

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)
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> を呼び出し、ジョブをポーリングします。単体のノードを実行するを参照してください。

リクエストとレスポンスの規約

  • 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 のようなスネークケースです。ワークフロー、実行、その他のほとんどのリソースは、キャメルケースです。
  • レスポンスのフィールドは増えていきます。新しいフィールドは随時追加されます。知らないフィールドがあってもエラーにせず、無視してください。
  • エラーの形式は 1 つです。失敗した呼び出しは、HTTP ステータスと { "error": { "code": "…", "message": "…" } } を返します。処理の分岐には code を使います。エラーを参照してください。

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

ヘッダー役割
X-Nodaro-Workspace組織内の 1 つのワークスペースで操作します。一覧をどのワークスペースから読み取るか、作成したものをどこに置くかが、このヘッダーで決まります。ワークスペースを参照してください。
X-Nodaro-Clientジョブを作成したクライアントを記録します。値は sdk/<version>、cli/<version>、extension/<name> のいずれかです。クライアントを識別するを参照してください。

同期と非同期

Nodaro の処理の多くは数秒から数分かかるため、API は非同期です。生成のルートはすぐに jobId を返し、ワークフローの実行は executionId とともに 202 Accepted を返します。その後、最終ステータスになるまで、2〜5 秒ごとにジョブまたは実行をポーリングします。1 分以内に終わる見込みのワークフローでは、POST /v1/api/run?wait=true が最大 600 秒間接続を保持し、結果を返します。インラインで処理されるテキストノード、無料のメディア処理、構造化出力の LLM 呼び出しなど、同期的に応答するルートもいくつかあります。詳しくは、同期と非同期を参照してください。ジョブのポーリングを省くには、Webhook エンドポイントを登録します。すると、自分のジョブが完了または失敗するたびに、Nodaro が署名付きのイベントをサーバーに送信します。

分野別のエンドポイント

実行する

ページ内容主なエンドポイント
ワークフロー保存したワークフローの実行(入力値の指定の有無を問わず)と、ワークフローの管理POST /v1/workflows/:id/run、POST /v1/api/run、GET /v1/api/schema
ノードワークフローを使わない単体のノードの実行、生成セッション、パレットとムードボード、利用できるノード、モデル、ピッカーの確認POST /v1/<node-type>、/v1/sessions、GET /v1/models
ジョブジョブのステータスと結果、評価とお気に入り、一括ポーリング、キャンセル、動画生成 Proの実行の制御GET /v1/jobs/:id/status、POST /v1/jobs/batch-status
実行ワークフローの実行のステータスと履歴GET /v1/workflow-executions/:id、GET /v1/workflows/:id/executions
アップロード画像、動画、オーディオのアップロード、URL の内容のストレージへのコピー、メディアライブラリの検索POST /v1/upload、GET /v1/library
Webhook署名付きのジョブイベントの自分のサーバーでの受信、HTTP 呼び出しやスケジュールによるワークフローの開始、結果の外部への送信/v1/webhook-endpoints、POST /v1/webhooks/:token

リソース

ページ内容主なエンドポイント
キャラクターキャラクター、ポートレートの候補、表情、ポーズ、モーション/v1/characters、POST /v1/generate-character
オブジェクト小道具、製品、乗り物と、そのメイン画像とバリエーション/v1/objects、POST /v1/generate-object
ロケーション場所と、そのメイン画像とバリエーション/v1/locations、POST /v1/generate-location
クリーチャークリーチャーと、そのメイン画像とバリエーション/v1/creatures
プリセット自分のノードプリセットの読み取りと書き込み、公開されている組み込みのカタログの読み取り/v1/node-presets、GET /v1/node-presets/factory
コミュニティ共有されたキャラクター、ロケーション、オブジェクトの閲覧と複製GET /v1/community/browse
パイプラインストーリー → 動画のパイプラインPOST /v1/pipelines/:id/branch
プロンプトウィザード生成ノード用のプロンプトの改善POST /v1/prompt-helper/wizard
Recast分析済みの動画を、自分のキャストで再生成POST /v1/recast
Video Remake短い動画の人物、ペット、商品、場所を、自分の画像に置き換えPOST /v1/video-remake
Trends既製の Video Remake のレシピを、自分の写真で実行POST /v1/trends/:slug/runs
スタジオプロダクションショット単位で組み立てるプロダクション/v1/studio/productions
音声とメディアボイス、ボイスチェンジ、吹き替え、メディアのインポート、オーディオツール/v1/voices、/v1/download-video、/v1/transcribe
コンテンツ権利リンクをインポートする前に、人が確認する宣言/v1/content-rights
キャラクター学習1 人のキャラクターでのモデルの学習POST /v1/characters/:id/train
3D シーン編集できる 3D シーンと、3D レンダリング ProPOST /v1/3d-scene/generate、POST /v1/pro-3d-render

アカウント

ページ内容主なエンドポイント
ワークスペースと組織ワークスペースでの操作、組織、メンバー、招待、使用量/v1/orgs、/v1/workspaces
クレジット残高、プランと価格、取引履歴、料金の確認GET /v1/credits/balance、GET /v1/credits/transactions

リファレンス

ページ内容
エラーエラーエンベロープ、すべてのエラーコード、ジョブの失敗のヒント
レート制限トークンごとの制限、ルートごとの制限、429 への対処方法
OpenAPI 仕様GET /v1/openapi.json で取得できる機械可読な仕様と、ほかの言語向けのクライアント

制限とエラー

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

言語別のクライアント

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

よくある質問

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 エディターを使うには、サブスクリプションが必要です。

最終更新

目次