REST API の概要

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

ベース URL

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

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

同期と非同期

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

分野別のエンドポイント

実行する

リソース

アカウント

リファレンス

制限とエラー

個人用 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 サーバーに接続します。