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

ワークフロー

API から保存済みの Nodaro のワークフローを実行し、新しい入力値を渡して、結果を待つかポーリングします。ワークフローの一覧表示、作成、更新、エクスポート、移動も行えます。

ワークフローは、接続されたノードを保存した 1 つのキャンバスです。API はワークフローを実行し、1 回の実行だけ新しい入力値を渡し、ほかのリソースと同じように管理できます。実行は 1 回のリクエストで開始し、executionId が返されます。実行が終わるまでそれをポーリングします。短い実行では、同じリクエストの中で結果を待つこともできます。

エンドポイント

ワークフローを実行する

メソッドパス説明
POST/v1/workflows/:id/run保存済みのワークフロー、またはその一部のノードを実行します。executionId とともに 202 を返します。
POST/v1/workflows/:id/render-final/estimate最終レンダリングの見積もりです。実行するノードとクレジットを返します。何も作成せず、何も請求しません。
GET/v1/api/workflowsその API トークンで実行できるワークフローを一覧表示します。?limit= と ?cursor= に対応します。
GET/v1/api/schema?workflowId=…ワークフローの入力フィールドと出力を、estimatedCredits とともに返します。
POST/v1/api/run新しい入力値でワークフローを実行します。結果を待つには ?wait=true&timeout=… を追加します。
GET/v1/api/status/:execId実行のステータス、ノードの数、使用したクレジット、そして完了後はその outcome です。
GET/v1/api/result/:execId実行のステータスが completed または failed になった後の出力です。
POST/v1/app/:slug/run公開したアプリを、そのフォームのフィールドで実行します。ミニアプリを参照してください。

ワークフローを管理する

メソッドパス説明
GET/v1/projects/:projectId/workflows1 つのプロジェクトのワークフローを、ノードとエッジを含まない形で返します。
GET/v1/workflowsすべてのプロジェクトにわたる、自分のワークフローです。
GET/v1/workflows/:id1 つのワークフローを、ノード、エッジ、設定とともに返します。
POST/v1/projects/:projectId/workflowsプロジェクト内にワークフローを作成します。
PATCH/v1/workflows/:idワークフローのフィールドを、任意の組み合わせで変更します。
DELETE/v1/workflows/:idワークフローを削除します。
GET/v1/workflows/:id/exportワークフローを JSON バンドルとしてエクスポートします。キャラクター、オブジェクト、ロケーションを含めるには ?assets=true を追加します。
POST/v1/workflows/importバンドルからワークフローを作成します。
POST/v1/workflows/:id/moveワークフローを別のプロジェクトに移動します。
GET/v1/workflows/shared-with-meほかの人が自分と共有したワークフローです。
GET/v1/mcp-conversations1 か月分の MCP 会話です。MCP 会話を参照してください。

共有、共同編集者、ワークフローごとの権限については、ワークスペースと組織を参照してください。

ワークフローを実行する 3 つの方法

エンドポイント認証情報入力値使うタイミング
POST /v1/workflows/:id/runどのトークンでも使えます。OAuth トークンには workflows:execute が必要です。保存済みの値です。nodeIds で一部だけを実行します。自分のアカウント、または OAuth ユーザーのために、保存されたとおりにワークフローを実行する場合です。
POST /v1/api/run個人用 API トークンinputs が、この実行の入力ノードの値を置き換えます。スクリプトが実行ごとに異なる値を必要とする場合、または結果を待ちたい場合です。
POST /v1/app/:slug/runどのトークンでも使えますアプリのフォームフィールドと、ノードの生の上書き値です。ワークフローが、整えられたフォームを持つアプリとして公開されている場合です。

5 つの /v1/api/ エンドポイントは、もともとの API トークン用の経路です。公開アプリより前からあり、引き続きサポートされていますが、入力を必要とする新しい連携では、通常はワークフローをアプリとして公開し、POST /v1/app/:slug/run を使います。このルートは、アプリのフィールドを、フラットな inputs と、任意の inputOverrides オブジェクト(生の { nodeId: { field: value } } という上書き値)として受け取ります。この 2 つはマージされ、両方が同じフィールドを設定している場合は inputOverrides が優先されます。公開されたスライダーのように、フィールドが数値のフラットな入力は、数値または数値の文字列を受け取ります。"0.4" は 0.4 としてノードに届きます。数値でない値はそのまま渡され、ノードはこれまでどおりに扱います。

保存したワークフローを実行する

POST /v1/workflows/:id/run は、保存されたとおりにワークフローの実行を開始します。すべてのノードを実行するには空のボディを送信し、一部だけを実行するには nodeIds を送信します。

curl -s -X POST https://app.nodaro.ai/v1/workflows/8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f/run \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
{ "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending" }
const { executionId } = await client.workflows.run(workflowId)

// Or run only some nodes:
await client.workflows.run(workflowId, { nodeIds: ['text-prompt-1', 'generate-image-1'] })
nodaro workflows run 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f --watch
nodaro workflows run 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f --node text-prompt-1 generate-image-1

プロパティ

型

応答は { executionId, status } を伴う 202 Accepted で、status は pending または running です。実行は GET /v1/workflow-executions/:id でポーリングします。詳しくは実行を参照してください。--watch を付けると、CLI が代わりにポーリングし、実行が失敗するとコード 2、キャンセルされるとコード 130 で終了します。

ステータスコード意味
402insufficient_credits自分のクレジットではまかなえない続行または最終レンダリングです。何も作成されていません。
403forbiddenワークフローは見えますが、実行する権限がありません。ワークスペースでは、実行に編集権限とアクティブなメンバーシップが必要です。
404not_foundそのワークフローが存在しないか、自分には見えません。
409already_runningワークフローには、すでにアクティブな実行があります。レスポンスには、その実行の executionId が含まれます。

通常の実行では、開始前に残高を確認しません。クレジットがノードの料金に足りない場合、そのノードはクレジット不足のエラーで失敗し、実行はその失敗を報告します。

実行を続ける

POST /v1/workflows/:id/run は、最初からやり直す代わりに、以前の実行を続けられます。その実行の ID を continueFromExecutionId に指定し、nodeIds と一緒に送信します。実行されるのは nodeIds だけです。ほかのすべてのノードは、以前の実行が記録したとおりの生成物を引き渡し、ワークフローの保存済みの結果は使いません。アップロードやアプリの入力など、その実行で使った入力がもう一度使われ、nodeIds より前のものは実行も請求もされません。

  • 以前の実行でも実行されなかったノードは、その実行のときと同じように、保存済みの結果を引き渡します。
  • 編集プランは、以前の実行が作ったプランに、現在のレビューを適用して引き渡します。別のプランに対して行ったレビューは無視されます。
  • 以前の実行で完了しなかったノードは何も引き渡さず、もう一度実行されることもありません。すべての入力がそのようなノードから来るノードは、その後のノードとともにスキップされます。
  • 以前の実行の inputOverrides がもう一度適用されます。送信した inputOverrides は、フィールドごとにその上に適用され、あなたの値が優先されます。

手作業で書いた最終レンダリングが、その一例です。レンダリングとその後のすべてのノードを、この実行に限りレンダリングを Final にして実行します。

{
  "nodeIds": ["<render node id>", "<every node after it>"],
  "inputOverrides": { "<render node id>": { "quality": "final" } },
  "continueFromExecutionId": "<a completed run whose render made a Preview>"
}

以前の実行は、あなたが開始した、このワークフロー自体の実行(公開アプリバージョンの実行ではないもの)で、completed で終わっている必要があります。そうでない場合、リクエストは実行が作られる前に拒否されます。

ステータスコード意味
400continuation_subset_requiredcontinueMode なしで、nodeIds がないか、空です。
400continuation_workflow_mismatch以前の実行は、別のワークフローの実行です。
400continuation_version_mismatch以前の実行は、ワークフローの公開アプリバージョンの実行です。失敗したアプリ実行は、アプリの再試行で続けてください。
400validation_errorcontinueFromExecutionId が実行の ID ではありません。
404continuation_not_foundその実行が存在しないか、あなたのものではありません。
409continuation_not_completed以前の実行が、まだ進行中か、失敗したか、キャンセルされました。

失敗した実行を続ける

保存済みのワークフローの失敗した実行は、完了した部分を残したまま、止まった所から続けられます。失敗した実行の ID を入れた continueFromExecutionId と、"continueMode": "from-failed" を送信します。

{
  "continueFromExecutionId": "<the run that failed>",
  "continueMode": "from-failed"
}
  • 残りだけが実行されます。失敗した実行が完了したノードは、すべて結果を引き渡し、再実行も再請求もされません。失敗したノードは、リストのすべての項目を含めて、最初から再実行されます。
  • 対象とするノード。nodeIds は任意です。省略すると、実行が開始されたときのノードで続行されます。名前を指定したノードの実行ならそのノード、全体の実行ならすべてのノードです。続行をさらに続行する場合も、最初の実行のノードが使われます。失敗したまま、または止められたままのノードは、上流で必要なノードと一緒に、すべて対象に加わります。
  • 指定したノードはすべて数えられます。nodeIds を指定すると、チェーンのどの実行でも実行されなかったノードは残りとして数えられるため、実行され、料金が計算されます。そのため、すべてのノードを指定すると、チェーンのどの実行でも省かれた作業のノードもそれぞれ実行されます。チェーンのいずれかの実行で実行されたノードは、指定しても再実行されません。
  • 実行されないノード。ソースやアップロード、トリガー、ピッカー、グループや収集のコンテナは、その実行が引き渡したものを引き渡します。ワークフローまたは実行の inputOverrides でスキップに設定されたノードは、実行されません。こうしたノードだけを指定すると、実行するものが何も残りません。
  • 以前の続行を含むチェーン。このルールができる前に実行された続行では、こうしたノードが完了として記録されています。そのチェーンでは、そのノードを指定しても完了として数えられるため、実行されません。実行するには、continueMode を付けずに nodeIds だけで、チェーンの最新の実行を続行します。これは、その実行が完了している場合にだけ使えます。失敗している場合は、まずそのノードを含めずに、失敗した箇所から続行してください。
  • 最新の続行が基準になります。続行には、それまでの実行が完了したものがすべて含まれます。そのため、サーバーは常に、その実行の最新の続行をもとに組み立てます。最新の続行が失敗している場合、リクエストは continuation_superseded で拒否され、その続行が示されます。代わりにそちらを続けてください。最新の続行が残りをすべて実行し終えている場合も、同じコードで作業の完了が伝えられます。残りの一部だけを完了している場合は、その続行をもとに実行が組み立てられます。202 の応答では、続行元の実行が continuedFrom に示されます。
  • プレビューで止まった続行。もう一度続けても同じプレビューで止まるため、リクエストは continuation_preview_pending で拒否されます。応答では、その続行が executionId に、そのレンダーが renderNodeIds に、そのエピソードを引き締めるノードが reviewNodeIds に示されます。next フィールドは、それらを仕上げる実行です。next を POST /v1/workflows/:id/run の本文として送信してください。
  • 先に残高を確認します。自分のクレジットではまかなえない続行は、開始前に 402 insufficient_credits で拒否されます。料金は、まだ実行する部分をもとに計算されます。失敗した実行が完了したノードに料金がかかることはありません。指定したノードのうち、チェーンのどの実行でも実行されなかったノードには、実行されるため料金がかかります。
  • Idempotency-Key ヘッダーを送信してください。同時に送られた 2 つの続行は、両方とも開始されることがあります。同じキーを使えば、リクエストを再試行しても、すでに開始した実行が "deduped": true 付きで返されます。

失敗した所からの続行は、上記のコードに加えて、次のコードで拒否されます。

ステータスコード意味
409continuation_not_failed実行が失敗していません。
409continuation_supersededその実行のより新しい続行が失敗した(代わりにそちらを続けてください)か、残りをすべて完了しています。その続行は executionId と supersededBy: { executionId, status } に示されます。
409continuation_preview_pending最新の続行がプレビューで止まっています。先にその next を送信してください。
409continuation_subset_required続ける対象が何も残っていないか、最初の実行が開始されたときのノードがワークフローに 1 つも残っていません。nodeIds でノードを指定するか、新しい実行を開始してください。
409already_runningこのワークフローの実行(続行を含む)が、まだ進行中です。その executionId が応答に含まれます。

公開アプリの実行は、ここでは続けられません。アプリの再試行を使ってください。エディターでは、同じ続行が失敗した所から続行です。ワークフローの実行を参照してください。

最終レンダリング

ノードを自分で並べる代わりに、レンダリングを指定して、残りをサーバーに任せられます。レンダリングのノード ID を入れた renderFinal と continueFromExecutionId を送信し、nodeIds と inputOverrides は送信しません。サーバーは、エディターの最終レンダリングと同じものを実行します。つまり、EDL 適用のレンダリングをこの実行に限り Final で行い、その後のすべてのノードを実行します。編集プランとレンダリングの間にカメラ切り替えがある場合は、先にカメラ切り替えがもう一度実行されます。編集プランはもう一度実行されません。この実行は続きの実行として扱われ、同じチェックを受けます。

{
  "renderFinal": { "renderNodeId": "<render node id>" },
  "continueFromExecutionId": "<a completed run whose render made a Preview>"
}

先に POST /v1/workflows/:id/render-final/estimate に { renderNodeId, continueFromExecutionId } のボディを送って見積もってください。見積もりは何も作成せず、何も請求しません。200 で { data: { renderNodeId, nodeIds, inputOverrides, estimatedCredits, holdCredits, sufficient, available } } を返します。

  • nodeIds と inputOverrides は、実行されるノードと、実行に使われる上書き値 { "<render node id>": { "quality": "final" } } です。
  • estimatedCredits は、レンダリングを Final にしたときの、実行されるノードの料金です。実行で LLM ノードが動く場合、応答には estimatedCreditsIsEstimate: true が加わります。そのノードには実際の使用分が請求されるので、数値は ≈N と表示してください。
  • holdCredits は、レンダリング中に実行が確保するクレジットです。UGC のクリップは、料金の約 2 倍が確保され、使われなかった分は完了時に戻ります。holdCredits が estimatedCredits を下回ることはありません。
  • sufficient はクレジットがその確保額に足りるかどうかを、available は使えるクレジットを示します。ワークスペースの予算やデプロイメントの請求アカウントが支払う場合、available は null です。
  • クレジットのないエディションでは、3 つの数値はすべて null です。

見積もりは、上の続きの実行のコードで拒否します。どちらのルートも、次のコードでも拒否します。

ステータスコード意味
400render_final_node_not_foundワークフローに、その ID のノードがありません。
400render_final_not_a_renderそのノードは、EDL 適用のレンダリングではありません。
400validation_errorrenderFinal が nodeIds または inputOverrides と一緒に送信されたか、continueFromExecutionId なしで送信されました。

最終レンダリングは、開始前に、見積もりの holdCredits で残高を確認します。足りない実行には、required(その確保額)と available を含む 402 insufficient_credits が返され、実行は作られません。確認するのは残高だけです。プランで使えないモデルや 1 日の上限は、実行がそのノードに達したときに、引き続きそのノードで拒否されます。

新しい入力値でワークフローを実行する

POST /v1/api/run は、この 1 回の実行に限り入力ノードの値を置き換える inputs オブジェクトを受け取ります。認証には個人用 API トークンを使います。inputs のキーはノード ID で、便宜上、一意なノードラベルも使えます。各キーの中には、テキストプロンプトの text のように、ノードの入力フィールドを指定します。

プロンプトテキストtext-prompt-1画像生成generate-image-1
サンプルのワークフロー:API の実行が置き換えるテキストを持つテキストノードが、画像生成ノードに渡されます。

下の例では、テキストノード(ID は text-prompt-1)を、画像生成ノードに接続したワークフローを実行します。

入力フィールドを見つける

GET /v1/api/schema は、ワークフローの入力を、各入力が受け取るフィールド、出力、実行にかかるクレジットの見積もりとともに一覧表示します。

curl -s "https://app.nodaro.ai/v1/api/schema?workflowId=$WORKFLOW_ID" \
  -H "Authorization: Bearer $NODARO_API_KEY"
{
  "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "name": "Sunset stills",
  "estimatedCredits": 50,
  "inputs": [
    { "nodeId": "text-prompt-1", "key": "text", "label": "Prompt", "type": "text" }
  ],
  "outputs": [
    { "nodeId": "generate-image-1", "label": "Generate Image", "type": "image" }
  ]
}

ワークフローに従量課金の LLM ノードが含まれる場合、応答には estimatedCreditsIsEstimate: true が加わり、estimatedCredits は見積もりになります。≈N と表示してください。まだ料金のない LLM のモデルを指定しているワークフローも、説明は返されます。その場合、estimatedCredits は省かれ、estimatedCreditsUnpriced: { reason: "llm_model_unpriced", modelId, message } がその理由を示します。そのワークフローの実行は拒否されます。まだ料金のないモデルを参照してください。

実行を開始する

curl -s -X POST https://app.nodaro.ai/v1/api/run \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
        "inputs": {
          "text-prompt-1": { "text": "a cat at sunset" }
        }
      }'
{ "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending" }

実行が終わるまでポーリングする

GET /v1/api/status/:execId は、ステータス、ノードの数、それまでに使用したクレジットを返します。ステータスが completed、failed、cancelled、timed_out、discarded のいずれかになるまで、2〜5 秒ごとにポーリングします。

結果を取得する

GET /v1/api/result/:execId は、completed または failed で終わった実行の出力を返します。cancelled、timed_out、discarded のいずれかで終わった実行では、代わりにステータスのレスポンスから errorMessage を読み取ってください。これらの実行には結果のペイロードがなく、結果のルートは 202 を返し続けます。

{
  "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b",
  "status": "completed",
  "outcome": "succeeded",
  "creditsUsed": 50,
  "durationMs": 12450,
  "errorMessage": null,
  "outputs": [
    {
      "nodeId": "generate-image-1",
      "label": "Generate Image",
      "type": "image",
      "url": "https://…/output.png"
    }
  ]
}

この一連の流れを 1 つのスクリプトにしたものと、同じ呼び出しを TypeScript で書いたものです。

BASE="https://app.nodaro.ai"
WORKFLOW_ID="8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f"

EXEC=$(curl -s -X POST "$BASE/v1/api/run" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"workflowId\": \"$WORKFLOW_ID\", \"inputs\": {\"text-prompt-1\": {\"text\": \"a cat at sunset\"}}}" \
  | jq -r .executionId)

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $NODARO_API_KEY" \
    "$BASE/v1/api/status/$EXEC" | jq -r .status)
  echo "Status: $STATUS"
  case "$STATUS" in completed|failed|cancelled|timed_out|discarded) break;; esac
  sleep 5
done

curl -s -H "Authorization: Bearer $NODARO_API_KEY" "$BASE/v1/api/result/$EXEC" | jq .
// The /v1/api/ lane has no dedicated SDK method: call it with client.request.
const schema = await client.request('GET', '/v1/api/schema', {
  query: { workflowId },
})

const { executionId } = await client.request<{ executionId: string }>('POST', '/v1/api/run', {
  body: { workflowId, inputs: { 'text-prompt-1': { text: 'a cat at sunset' } } },
})

const final = ['completed', 'failed', 'cancelled', 'timed_out', 'discarded']
let status = 'pending'
while (!final.includes(status)) {
  await new Promise((r) => setTimeout(r, 3_000))
  ;({ status } = await client.request<{ status: string }>('GET', `/v1/api/status/${executionId}`))
}

const result = await client.request('GET', `/v1/api/result/${executionId}`)

CLI は、保存された値のままでワークフローを実行します。ターミナルから値を渡すには、ワークフローをアプリとして公開し、nodaro apps run <slug> --input prompt="…" を実行します。

プロパティ

型

ワークフローのスコープを持つトークンは、そのスコープ内のワークフローだけを実行できます。それ以外のワークフローには 403 forbidden が返されます。POST /v1/api/run と GET /v1/api/workflows は、トークンの 1 分あたりの制限にカウントされます。ステータス、結果、スキーマの読み取りはカウントされません。レート制限を参照してください。

同期か非同期か

POST /v1/api/run は、デフォルトでは非同期です。すぐに { executionId, status: "pending" } を伴う 202 Accepted を返し、その後ポーリングします。

短いワークフローでは、終わるまで接続を保持できます。

POST /v1/api/run?wait=true&timeout=120
  • サーバーは、最大 timeout 秒まで、5 秒ごとに実行を確認します。デフォルトは 120、最大は 600 です。
  • 実行がその時間内に終わった場合、レスポンスは GET /v1/api/result/:execId と同じペイロードです。status は completed、failed、cancelled、timed_out、discarded のいずれかです。
  • 終わらなかった場合、レスポンスは { executionId, status: "pending" } を伴う 202 になるので、そこからポーリングします。

1 分未満で終わると見込める実行、たとえばテキスト生成や軽い画像処理には、同期の形式を使います。動画のレンダリングやアップスケールを行うワークフローには、非同期の形式を使います。SDK では、クライアントがデフォルトで 60 秒後にあきらめるため、createClient の timeoutMs を、自分の timeout より大きい値に設定してください。

POST /v1/workflows/:id/run と生成系のルートは、常に非同期です。単体のノードについては、SDK の nodes.runAndWait が代わりにジョブをポーリングします。単体のノードを実行するを参照してください。

新しいものが見つからない実行

スケジュール実行は、読み込むフィードに新しい投稿がないため、何もすることがない場合がよくあります。そのような実行は、failed ではなく completed で終わります。

  • モデルや音声にテキストを送るノードは、そのテキストが空で、この実行で何も生成しなかったノードから来ている場合にスキップされます。その後のノードもスキップされます。該当するノードは、テキスト生成、脚本生成、テキストから音声、音楽生成、テキストからオーディオです。
  • Webhook 出力やソーシャル投稿のノードなど、接続されたものを送る出力ノードは、この実行ですべての接続が何も運ばなかった場合にスキップされます。
  • スキップされたノードには何も請求されません。新しい投稿を返さない Telegram チャンネルフィードは課金されません。

GET /v1/api/status/:execId、GET /v1/api/result/:execId、そして ?wait=true の応答は、そのような実行に "outcome": "nothing_new" を含めます。ほかの完了した実行は "succeeded" です。失敗またはキャンセルされた実行には outcome がなく、status だけがあります。何も問題は起きていないため、errorMessage は null のままです。GET /v1/workflow-executions/:id では、スキップされた各ノードが { "status": "skipped", "skipReason": "empty_input" } になります。

プロンプトを入力したノードは、接続が空でも実行されます。そのプロンプトがリクエストになるためです。接続がまったくないノードは、これまでどおり検証エラーで失敗します。対象になるのは、この実行で何も運ばなかった接続だけです。

実行で変更できないもの

実行のリクエストで、ワークフローの送信系のノードの宛先を変更することはできません。ワークフローがどこに送信し、どこから取得するかは、POST /v1/workflows/:id/run、POST /v1/api/run、POST /v1/app/:slug/run を含むすべての実行エンドポイントで、ワークフロー自身が決めます。

送信系のノードとは、Webhook 出力と、SNS に公開のような SNS への公開ノード、そして取得系のノードです。取得系のノードには、Web スクレイピング、Telegram チャンネルフィード、動画 URLなどがあります。これらのノードでは、上書きで次のものを変更できません。

  • 名前が Url または Urls で終わるフィールド。
  • target、targets、query、channel、chatId、connectionId、credentialId、platform、webhook、endpoint、host、privacy。
  • 取得系のノードがどの宛先フィールドを読み取るかを決める、actor と mode のセレクターです。

このルールは、オブジェクトや fieldMappings のエントリーの中にネストした値にも及び、新しいアドレスだけでなく空の値にも適用されます。宛先を空にすると、そのノードは代わりに上流のテキストを読み取ってしまうためです。このようなリクエストは、何も実行される前に 400 locked_field を返します。エラーには、問題のあるフィールドが最大 10 個まで列挙され、残りは件数で示されます。また、そのようなノードで 32 階層を超えてネストした上書きは、無条件に拒否されます。

これらのノードにあるキャプションや上限といった通常のフィールド、そしてアップロードやリファレンス音声のような入力ノードのメディアの url フィールドは、引き続き上書きできます。

実行では、サブワークフローノードが何を実行するかも変更できません。その workflowId、selectedRouteId、routeSnapshot は、直接設定しても fieldMappings のエントリで設定しても、400 locked_field が返されます。ノードがどのワークフローを、そのどの部分を実行するかは、ワークフロー自体が決めます。

UGC 動画のノードでは、実行で設定できるのは、UGC クリエイターの source、gender、photoUrl と、UGC スクリプトの targetDurationSec だけです。保持された結果、スクリプト、クリップなど、それ以外のフィールドには 400 locked_field が返されます。自分の写真に設定された UGC クリエイターの実行で、実行する人自身の写真が渡されない場合は、何も請求される前に 400 ugc_photo_required が返されます。UGC クリエイターとアプリでの UGC 動画を参照してください。

公開されたアプリでは、選択肢が固定のリストである、公開されたモデルやクイック設定は、そのリストに制限されます。リストにない値には 400 validation_error が返され、設定の範囲外の数値にも同じエラーが返されます。inputOverrides の null は、その実行でノードのそのフィールドをクリアするので、ノード自体のデフォルトが適用されます。一方、フラットな入力の null は破棄されるので、保存された値が適用されます。モデルとクイック設定のフィールドを参照してください。

パラメーターの補正

画像と動画の生成ルートは、モデルに関わらず、aspectRatio、resolution、quality について 1 つの語彙を受け付けます。画像のルートでは、この語彙に background、outputFormat、gifFrames、gifFrameDurationMs、svgLevel も含まれます。すべてに対応しているモデルはありません。選んだモデルが対応していない値を拒否する代わりに、サーバーはそれをモデルが対応する値に補正し、何を変更したかを伝えます。ワークフローの途中で拒否すると、すでに生成が済んでいて課金されている、隣のノードまですべて失敗してしまいます。

値を補正するルートは、POST /v1/generate-image、/v1/image-to-image、/v1/edit-image、/v1/text-to-video、/v1/generate-video です。

{
  "jobId": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
  "adjustments": [
    {
      "field": "aspectRatio",
      "from": "3:2",
      "to": "auto",
      "reason": "GPT Image 2 does not support aspectRatio \"3:2\" — using \"auto\" instead. Supported: auto, 1:1, 16:9, 9:16, 4:3, 3:4."
    }
  ]
}
  • adjustments は、何も変更がなければ存在しません。有効なリクエストのレスポンスは、{ "jobId": "…" } だけになります。
  • to は、モデルにその設定がない場合は存在せず、値は取り除かれます。たとえば、アップスケーラーに送信した aspectRatio です。
  • クレジットは、補正後の値に従います。GPT Image 2.5 Flare に 2K の 9:8 をリクエストすると、GPT Image 2.5 は 9:8 を 1K でしかレンダリングしないため、1K でレンダリングされ、1K の料金が課金されます。
  • aspectRatio: "auto" は写真の形を保ちます。対象は /v1/image-to-image と /v1/edit-image です。形を保つ独自の auto を持つモデルは、そのまま受け取ります。持たないモデルでは、サーバーが imageUrl のサイズを読み取り、モデルが対応する最も近い比率を使い、その選択を adjustments に報告します。GPT Image 2.6(gpt-image-2-6-*)も同じように扱われます。このモデル独自の auto は、縦長の写真を正方形でレンダリングするためです。たとえば、seedream-5-pro-i2i に送った 1104x1472 の縦長の画像は 3:4 で、gpt-image-2-6-flare-i2i に送った 768x1024 の画像も 3:4 でレンダリングされます。サイズを読み取れない場合、auto はモデルの最初に記載された比率になり、GPT Image 2.6 ではモデル独自の auto になります。これらのモデルでは、比率によって料金は変わりません。auto は、それを記載するすべてのモデルで選択肢として残ります。変わるのは送られる値だけです。
  • /v1/generate-image も、写真が接続されている場合は同じように動作します。写真とは、リクエストがモデルに送る最初の画像です。baseImageUrl(インペイントまたはリファイン)が設定されていればそれ、なければ最初のリファレンス画像(referenceImageUrls、または connectedReferences から作られる最初の画像)です。写真がない場合、独自の auto を持たないモデルでの auto は、モデルの最初に記載された比率になり、GPT Image 2.6 はモデル独自の auto を受け取ります。
  • 一部の編集モデルで aspectRatio を省略すると auto になります。/v1/image-to-image で、gpt-image-2-6-flare-i2i(デフォルト)、gpt-image-2-6-sunburst-i2i、gpt-image-2-6-economy-i2i、gpt-image-2-5-flare-i2i、gpt-image-2-5-sunburst-i2i、gpt-image-2-i2i、minimax-h3-image-i2i、seedream-5-5-i2i への比率を指定しないリクエストは、"auto" を送ったリクエストと同じように実行されます。モデルの 16:9 のデフォルトは使われません。GPT Image 2 と 2.5 は、写真の形を保つ独自の auto を受け取ります。MiniMax H3 Image は最初の画像に合わせる独自の auto を、Seedream 5.5 は独自の auto を受け取ります。GPT Image 2.6 は、上記のとおり、写真に最も近い比率を受け取ります。ジョブには送られた比率が記録され、料金は変わりません。これらのモデルの料金は、品質、サイズ、入力画像の数で決まるためです。ほかのモデルは、比率を指定しない場合、それぞれのデフォルトを使います。
  • outputFormat も同じように補正されます。対象は、GET /v1/models で outputFormats を記載するモデルです。値は png(デフォルト)、jpeg、webp、gif、svg です。形式に応じた設定も、形式に合わせて補正されます。
    • GIF:512×512 の正方形のフレームが 2〜16 枚です。aspectRatio は 1:1 になり、resolution は外され、それぞれの変更が報告されます。ただし、auto の比率は報告されません。gifFrames(2〜16、デフォルト 9)と gifFrameDurationMs(20〜2,000 ms、10 刻み、デフォルト 200)は、範囲内の刻みの値に移されます。省略した場合、ジョブにはデフォルトが記録されます。
    • SVG:svgLevel(standard(デフォルト)、detailed、max)も同じように補正されます。auto 以外の background は auto になります。SVG は背景の設定を受け付けないためです。
    • 背景:transparent の背景が保たれるのは png と webp だけです。gif または jpeg では auto になって報告され、サイズは 1K に移されません。
    • ほかの形式:モデルが書き出さない形式は、モデルの最初の形式に移されます。形式を持たないモデルでは、このフィールドは外されます。ほかの形式と一緒に送られた GIF や SVG の設定は、補正の報告なしに無視されます。
    • マスク:gif または svg と一緒の maskUrl は、何も確保される前に 400 になります。
    • 料金:PNG、JPEG、WebP の料金は同じです。GIF の料金は品質とフレーム数の帯(2〜8、9〜12、13〜16)で決まり、SVG の料金は、そのサイズの PNG にレベルの分を加えたものです。画像生成の形式を参照してください。
    • 結果:ジョブの output_data は、保存されたファイルの種類を imageMimeType(image/jpeg、image/webp、image/gif、image/svg+xml)で示し、width と height も含みます。GIF と SVG には、PNG の静止画が thumbnailUrl に付きます。SVG は保存前にクリーンアップされます。安全に読み取れない SVG はジョブを失敗させ、そのジョブのクレジットは返還されます。
  • /v1/image-to-image の maskUrl は、モデル自身のインペイント用マスクです。白が変更する領域、黒が保つ領域です。適用されるのは ideogram-edit、flux-fill、gpt-image-2-6-flare-i2i、gpt-image-2-6-sunburst-i2i、つまり GET /v1/models のエントリーに mask の機能が記載されているモデルです。ほかのモデルは無視します。
    • GPT Image 2.6 は、画像のそれ以外の部分を保ちます。モデルは画像全体を描き直すため、マスクの外側にはすべて元の画像(imageUrl)が貼り戻され、塗った領域の内側に数ピクセル幅のソフトな境界ができます。マスクのグレーは部分的な変更になるので、ソフトな境界はソフトなまま保たれます。ジョブの output_data.maskComposited は true です。
    • 結果は imageUrl のサイズで、指定した形式になります。PNG では、マスクの外側に元の画像のピクセルがそのまま残ります。JPEG と WebP は、もう一度エンコードされます。
    • GPT Image 2.6 では、サイズと形が写真に合わせて決まります。どの aspectRatio も auto、つまり写真に最も近い対応比率になります。resolution は、長辺が写真の長辺に最も近いサイズ(1K、2K、4K)になります。実行はそのサイズで課金され、どちらの変更も adjustments で返されます。写真のサイズを読み取れない場合は、指定した resolution が保たれます。
    • マスクに追加料金はかかりません。実行は、そのサイズでマスクなしの同じ編集として課金され、マスクは入力画像として数えられません。
  • 保存済みのワークフローも補正されます。API または MCP を通じて保存したワークフローは、書き込み時に同じ補正を受けます。例外は、generate-image、image-to-image、modify-image、edit-image のノードの auto です。これは保持され、ワークフローの実行時に写真に合わせて決まります。
  • 各モデルが対応する値は、GET /v1/models にあります。モデルを調べるを参照してください。

動画のルートでの補正

/v1/text-to-video と /v1/generate-video は、同じ形式で adjustments を返します。/v1/generate-video は、各補正の reason を、voice_unsupported_for_provider のようなパラメーター以外の警告と並べて、warnings の配列にも繰り返します。どの設定が変わったかを知りたいときは adjustments を読んでください。この 2 つが食い違うことはありません。

  • 対応していない値は、最も近い選択肢に切り上げ・切り下げされます。最も安い値や最初の値になることはありません。1080p が上限のモデルに 4k をリクエストすると、480p ではなく 1080p でレンダリングされ、縦長の 9:21 は、16:9 ではなく 9:16 になります。
  • resolution を省略すると、その料金がかかる段階で送信されます。プラットフォームがモデルのデフォルトの段階を定めている場合、その段階が課金され、モデルにもその段階がリクエストされます。この値はジョブの input_data に表示されるため、何が送信されたかを必ず確認できます。
  • 料金の計算前に、表記が正規化されます。4K は 4k として読み取られるため、4K の段階で課金され、レンダリングされます。
  • 一部のモデルは、それ以外の値に対して固定の段階でレンダリングします。MiniMax H3 は、768P 以外のすべての値に対して 2K でレンダリングし、Wan 3.0 ファミリーと PixVerse V6 Max は 720p で、Grok Imagine 1.5 は 480p でレンダリングします。これらのモデルでは、モデルが実際に出力する段階に合わせて補正されるため、料金がレンダリング結果と一致します。モデルの GET /v1/models のエントリーでは、これが unlistedResolutionRendersAs に示されます。
  • 長さは、モデルがレンダリングする長さで課金されます。duration のないリクエストは、モデル自身のデフォルトの長さ(GET /v1/models の defaultDuration)でレンダリングされ、その長さで課金されます。モデルが対応していない duration は、対応する最も近い長さに移動し、同じ距離の場合は短いほうになります。この変更は adjustments に報告されます。たとえば、7 秒のリクエストは、Kling では 5 秒でレンダリングされて課金され、LTX 2.3 のモデルでは 6 秒でレンダリングされて課金されます。
  • duration: -1 は、対応するモデルでは「自動」を意味します。Seedance 2 ファミリー(GET /v1/models で autoDuration: true)が対応しています。モデルがクリップの長さを選びます。リファレンス動画を編集する場合は、その元の動画の長さになります。「自動」での実行では、モデルの最長のクリップ分のクレジットが確保され、実際に生成された長さを超える分が返還されます。リファレンス動画の長さを測定できた場合は、代わりに最長のリファレンス動画の長さを秒単位に切り上げて 1 秒を足した分が確保されます。モデルはどのリファレンス動画も編集しうるためです。ただし、モデルの最長のクリップを超えることはありません。Seedance 2.5 で、長さが自動のまま referenceTaskType: "reference" を宣言したリクエストは、モデルが作れる最長の出力で確保され、作った分が課金されます。Seedance 2.5 のリファレンスのタスクタイプを参照してください。ほかのモデルは -1 を無視し、デフォルトの長さでレンダリングします。

キャラクターとロケーションの画像ルート(/v1/generate-character、/v1/generate-character-asset、/v1/generate-location、/v1/generate-location-asset)も、同じ方法で quality と resolution を補正しますが、adjustments は返しません。補正後の値は、GET /v1/jobs/:id から取得したジョブの input_data でのみ確認できます。

ワークフローを管理する

一覧表示と読み取り

GET /v1/projects/:projectId/workflows は、プロジェクトのワークフローを、nodes、edges、settings を含まない形で返します。GET /v1/workflows/:id は、1 つのワークフローを完全な形で返します。組織では、一覧は自分が操作しているワークスペースに従います。ワークスペースを参照してください。

curl -s https://app.nodaro.ai/v1/projects/$PROJECT_ID/workflows \
  -H "Authorization: Bearer $NODARO_API_KEY" | jq '.data[] | {id, name}'
const { data: workflows } = await client.workflows.list({ projectId })
const { data: workflow } = await client.workflows.get(workflows[0].id)
console.log(workflow.nodes.length)
nodaro workflows list --project $PROJECT_ID --json
nodaro workflows get 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f

作成と更新

POST /v1/projects/:projectId/workflows で、プロジェクト内にワークフローを作成します。プロジェクト以外はすべて任意で、指定しない場合はサーバーのデフォルト値が使われます。

const { data: wf } = await client.workflows.create({
  projectId,
  name: 'My workflow',
  nodes: [],
  edges: [],
})

PATCH /v1/workflows/:id は、フィールドを任意の組み合わせで変更します。同時編集に対して安全な更新にするには、直前の読み取りで得た整数の version を、expectedVersion として送信します。それ以降にワークフローが変更されていた場合、更新は 409 workflow_conflict で拒否され、エラーには currentVersion、currentUpdatedAt、そして現在のワークフロー全体である currentRecord が含まれます。追加の読み取りをせずに、変更を currentRecord にマージして、もう一度保存してください。タイムスタンプである expectedUpdatedAt も、同じように機能します。

import { WorkflowConflictError } from '@nodaro/sdk'

try {
  await client.workflows.update(id, { name: 'Renamed', expectedVersion: 7 })
} catch (err) {
  if (err instanceof WorkflowConflictError && err.currentRecord) {
    await client.workflows.update(id, { name: 'Renamed', expectedVersion: err.currentVersion })
  } else throw err
}
  • ノードの data にある実行状態の値、たとえば実行ステータス、現在のジョブ、進行状況は、保存時に取り除かれ、保存されません。
  • thumbnailUrl は、すでにホストされている画像から、ワークフローのプレビュー画像を設定します。null を指定すると解除されます。
  • edges だけを送信して動画オーバーレイのレイヤーを接続する保存は、そのノードを書き換えるため、expectedVersion がなくても、読み取り後にワークフローが変更されていた場合は 409 workflow_conflict を返します。
  • visibility は private または workspace です。変更できるのは作成者かワークスペースの管理者だけで、ワークスペースの外にあるワークフローには 400 not_workspace_scoped が返されます。

削除

DELETE /v1/workflows/:id は、ワークフローを削除します。削除できるのは作成者とワークスペースの管理者だけで、共同編集者にはできません。存在しないワークフローや、自分には見えないワークフローの削除は 404 を返すため、削除が黙って成功することはありません。ワークフローが見えても削除できない共同編集者には、403 が返されます。

エクスポートとインポート

GET /v1/workflows/:id/export は、ワークフローを持ち運び可能な JSON バンドルとして返します。?assets=true を付けると、そのワークフローが使うキャラクター、オブジェクト、ロケーションも、自分のものであればバンドルに含まれます。localhost やプライベートネットワーク上のファイルのように、ノードがほかのインストール環境から取得できないメディアを指している場合、バンドルはそれらを portability.unreachableMedia に一覧表示します。閲覧権限の人は、所有者の Studio の下書きを除いたワークフローを受け取ります。空のメディア枠、実行中を示す印、テイクの音声プランです。そのとき、バンドルには、それらの部分だけが使うアセットは含まれません。GET /v1/workflows/:id も、閲覧権限の人には同じ部分を除いて返します。

POST /v1/workflows/import は、バンドルからワークフローを作成します。

POST /v1/workflows/import
{ "projectId": "<project uuid>", "workflow_json": { "version": 1, "name": "…", "nodes": [], "edges": [] } }

インポートは、バンドルされたキャラクター、オブジェクト、クリーチャー、ロケーションを自分のアカウントの下に再作成し、ノードをそれらに向け直します。取得できるメディアは、このインストール環境のストレージにコピーされます。ワークフローのメディア用に最大 25 ファイル、バンドルされたエンティティ用にさらに最大 25 ファイルで、画像は最大 20 MB、動画や音声は最大 50 MB です。レスポンスには、新しいワークフローと importReport が含まれます。

フィールド意味
rehostedこのインストール環境にコピーされたファイルの数です。
unreachableプライベートホスト上のメディアで、元の場所を指したままです。これらのノードは、ファイルが再度アップロードされるまで実行されません。
skippedコピーできなかったメディアで、HTTP 404 のような理由が付きます。
assetIdMapバンドルされた各エンティティの ID を、そのために作成された行に対応付けたものです。
assetsSkippedストレージの容量が足りず、作成されなかったエンティティです。それでもワークフロー自体は作成されます。

CLI からは、nodaro workflows export <id> --with-assets --output bundle.json を実行し、続けて nodaro workflows import bundle.json --project <projectId> を実行します。何が引き継がれるかについては、インポートとエクスポートを参照してください。

MCP 会話

GET /v1/mcp-conversations?month=2026-10&sources=claude,chatgpt

このルートは、1 か月分の MCP 会話を新しい順に一覧表示します。各会話は、アシスタントがそのステップから組み立てたワークフローです。MCP 会話がワークフローになる仕組みを参照してください。OAuth トークンには workflows:read が必要です。

クエリ意味
monthYYYY-MM です。デフォルトは、会話がある最新の月です。
sources残すソースで、カンマで区切ります。claude、claude-code、chatgpt、またはほかのクライアントの小文字の名前です。デフォルトはすべてのソースです。

レスポンスには次のものが含まれます。

  • month:一覧表示した月です。
  • months:会話があるすべての月で、新しい順に、それぞれの件数とともに示されます。
  • sources:一覧表示した月のソースで、それぞれの件数とともに示されます。1 つのソースは、1 つの製品の接続をまとめたものです。「Claude Code (nodaro)」と「Claude Code (staging)」は、1 つの claude-code ソースです。connections にそれらが示されます。
  • data:会話です。各会話には次のものがあります。
    • id と projectId。会話はワークフローなので、ワークフローのルートで開く、名前を変更する、エクスポートする、コピーする、削除することができます。
    • name、client、clientLabel、clientName。
    • startedAt、lastActivityAt、live。live は、最後のステップから 30 分未満の間 true です。
    • firstRequest:アシスタントが渡した場合の、あなたの最初のリクエストです。
    • nodeCount と、種類ごとの counts(image、video、audio)。
    • credits:そのジョブに請求されたクレジットです。クレジットが課金されない環境では null です。
    • cover:{ url, kind, setByUser }。あなたが設定したカバー、なければ最新の結果です。

会話に対する DELETE /v1/workflows/:id は、そのワークフローを削除します。アシスタントが作ったジョブはワークフローに保存されていないので、その画像と動画はライブラリに残ります。エディターで開始した実行は、ほかのワークフローと同じように一緒に削除されます。月のハブワークフローは削除できず、ルートは 409 mcp_hub を返します。一部のワークフローに限定された個人用 API キーは会話を一覧表示できず、403 が返ります。

別のプロジェクトへの移動

POST /v1/workflows/:id/move
{ "projectId": "…" }

移動はワークフローへの書き込みなので、OAuth トークンには workflows:write が必要です。projectId を指定した PATCH /v1/workflows/:id も同じ動作をし、同じルールに従います。移動できるのは、自分が作成した作業です。組織の中では、ワークスペースの管理者が、自分の管理する 2 つのワークスペースの間で作業を移動することもできます。個人のプロジェクトは、移動元と移動先の両方が自分のものである必要があります。

ステータスコード意味
400validation_errorワークフローは、すでにそのプロジェクトにあります。
403not_permittedそのワークフローを移動する権限がないか、その移動先に移動する権限がありません。
404not_foundそのワークフローが存在しないか、自分にはそのプロジェクトが存在しません。
409move_blockedその作業は、課題のために作成されたものです。
409workspace_archived移動先のワークスペースがアーカイブされています。

ワークスペースが変わる移動では、ワークフローの共同編集者への権限が取り消され、レスポンスに報告されます。これにより、アクセスを失った人に伝えられます。

{
  "data": { "id": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f", "projectId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716" },
  "droppedCollaborators": [{ "userId": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f70812", "name": "Sam" }]
}

PATCH の形式では、droppedCollaborators は、権限が取り消された場合にのみ含まれます。

どちらの形式も、移動したワークフローを、現在の状態で data に返します。移動後のあなた自身のアクセス権が edit より下の場合は、view の閲覧者と同じ形で受け取ります。たとえば、ワークスペースの管理者が、管理者は閲覧しかできないワークスペースにメンバーの作品を移動した場合です。ワークスペースと組織を参照してください。

ワークフローの OAuth スコープ

スコープルート
workflows:readGET /v1/projects/:projectId/workflows, GET /v1/workflows, GET /v1/workflows/:id, GET /v1/workflows/:id/export, GET /v1/mcp-conversations
workflows:write作成、更新、削除、インポート、移動、および POST /v1/workflows/:parentId/sub-workflows
workflows:executePOST /v1/workflows/:id/run

個人用 API トークンには、スコープは必要ありません。OAuth アプリを参照してください。

スタジオプロダクションのノード

キャンバスの一部のノードは、スタジオプロダクションに属し、リンクされたフレームに依存します。これらは、スタジオプロダクション API を通じて生成する必要があります。POST /v1/workflows/:id/run で実行したり、直接生成したりすると、400 sequence_execution_required が返されます。スタジオプロダクションを参照してください。

よくある質問

API から Nodaro のワークフローを実行するにはどうすればよいですか?

POST /v1/workflows/:id/run を送信します。保存済みのワークフローが実行され、ポーリングする executionId とともに 202 が返ります。1 回の実行だけ入力値を変更するには、ノード ID をキーにした inputOverrides オブジェクトを追加するか、inputs オブジェクトを付けて POST /v1/api/run を呼び出します。

ワークフローの実行に入力値を渡すにはどうすればよいですか?

POST /v1/api/run に inputs オブジェクトを送信します。キーはノード ID か一意なノードラベルで、その中にノードのフィールド(たとえば text)を指定します。GET /v1/api/schema は、ワークフローの入力フィールドを一覧表示します。

1 回のリクエストで、ワークフローの結果を待てますか?

はい。POST /v1/api/run に ?wait=true&timeout=120 を追加します。サーバーは接続を最大 600 秒保持して出力を返します。実行がまだ続いている場合は、executionId とともに 202 を返すので、そこからポーリングしてください。

API が、送信したアスペクト比や解像度を変更したのはなぜですか?

選んだモデルがその値に対応していないため、実行を失敗させる代わりに、Nodaro がモデルの対応する最も近い値に補正したためです。レスポンスの adjustments に、すべての変更が一覧表示されます。クレジットは、補正後の値に基づいて課金されます。

API での実行で、ワークフローが結果を送る先を変更できますか?

いいえ。Webhook 出力の URL や、SNS への公開先のアカウントなど、送信系のノードの宛先フィールドは、実行によって上書きできません。それを試みたリクエストには 400 locked_field が返されます。

最終更新

目次