ミニアプリの埋め込み
公開された Nodaro のミニアプリを、埋め込みコードで、または REST API 上に作った独自のフォームで、自分のプロダクトの中で実行します。入力の読み取りから、実行、結果、エラーまでを扱います。
ミニアプリを埋め込むとは、すでに公開されている Nodaro のアプリを、自分のプロダクトから実行することです。アプリの埋め込みコードをページに貼り付けることも、REST API の上に自分のフォームを構築することもできます。アプリの入力を読み取り、実行を開始し、ポーリングし、結果を表示します。アプリ自体は Nodaro の中にとどまり、自分のプロダクトは入力を集め、出力を表示します。
埋め込みの 2 つの方法
| 埋め込みコード | 独自のインターフェース | |
|---|---|---|
| 手間 | iframe タグを 1 つ貼り付けるだけです。 | フォームと、小さなサーバールートを構築します。 |
| 見た目 | Nodaro アプリの画面です。 | 自分のデザインです。 |
| 実行の名義 | 閲覧者本人で、その人自身の Nodaro セッションを使います。 | トークンに紐づくアカウントです。 |
埋め込みコードを貼り付ける
アプリの埋め込み設定を開く
Nodaro で、ミニアプリを開き、マイミニアプリを選んで、アプリのカードにある埋め込みをクリックします。
自分のドメインを許可する
埋め込みを許可するドメインの欄に、https://example.com のような自分のサイトのオリジンを入力し、追加をクリックします。ドメインを 1 つ以上追加するまで、埋め込みはブロックされます。
コードを自分のページにコピーする
埋め込みコードをコピーをクリックし、タグを自分のページに貼り付けます。
<iframe src="https://app.nodaro.ai/embed/your-app-slug" width="100%" height="600" frameborder="0" allow="clipboard-write"></iframe>独自のインターフェースを構築する
このページの残りの部分では、REST API を使って、公開されたアプリのための独自の Web インターフェースやモバイルインターフェースを構築します。この内容は単体で完結しているため、AI コードジェネレーターにそのまま渡すこともできます。このページの URL に .md を追加すると、Markdown 版が手に入ります。
最初に知っておきたい 3 つのこと
| ベース URL | Nodaro Cloud では https://app.nodaro.ai、セルフホスティング環境では自分のインストール先のアドレスです。 |
| アプリ識別子 | slug です。公開されたアプリの URL の最後の部分です。https://app.nodaro.ai/app/my-cool-app の場合、スラッグは my-cool-app です。 |
| 実行の形 | 非同期です。POST /v1/app/{slug}/run はすぐに runId を返し、結果は GET /v1/app/{slug}/runs/{runId} をポーリングして受け取ります。実行からのコールバックはありません。 |
トークンを必要としない 2 つの公開エンドポイントが、フォームに必要なすべての情報を教えてくれます。
GET /v1/app/{slug}は、アプリの入力とメタデータを返します。GET /v1/nodes/{type}は、1 つのノードタイプのフィールドを返します。
ステップ 1:アプリの入力を読み取る
curl https://app.nodaro.ai/v1/app/<slug>自分のインターフェースにとって重要なフィールドは、次のとおりです。
{
"id": "uuid",
"name": "Headline Generator",
"description": "...",
"iconUrl": "https://...",
"version": 3, // the latest version
"estimatedCredits": 5, // the listed price: a run, with any Render final after it
"perMinuteCredits": 0, // per minute of the recording the app is given; 0 when the price does not depend on it
"perItemCredits": 0, // per item beyond the saved items of a list the user fills; 0 when none
"maxEstimatedCredits": 9, // "up to": the most a run can cost over the user's choices (with
"maxPerMinuteCredits": 0, // maxPerMinuteCredits and maxPerItemCredits); present only when it
"maxPerItemCredits": 0, // differs from the "from" figures above
"estimatedCreditsIsEstimate": true, // present when the price holds a metered LLM call's estimate: show "~5"
"runEstimatedCredits": 5, // the run alone: the listed price without its Render final part
"runPerMinuteCredits": 0, // ...and its per-minute and per-item parts
"runPerItemCredits": 0,
"editPlanPerMinute": false, // true when an Edit Plan node is charged per started minute of the recording
"maxRunsPerUserPerDay": null, // or a number
"thumbnailNodeId": "node-abc", // the node whose output is the main result
"snapshotNodes": [ // the workflow's nodes
{
"id": "node-abc",
"type": "generate-image", // use it in step 2
"data": {
"prompt": "default prompt", // the current value of each field
"aspectRatio": "1:1"
}
}
],
"snapshotEdges": [ /* the connections, rarely needed by your interface */ ],
"snapshotSettings": {
"presentationSettings": {
"inputItems": [ // the form schema
{ "type": "field", "id": "item-1", "nodeId": "node-abc", "field": "prompt", "allowedValues": null, "maxLength": 1200 },
{ "type": "field", "id": "item-2", "nodeId": "node-abc", "field": "aspectRatio", "allowedValues": ["1:1", "16:9", "9:16"] }
]
}
},
"versions": [{ "version": 3, "id": "...", "createdAt": "..." }]
}inputItems は、公開者が設計したフォームです。これをたどり、すべての group の中に入り、すべての field 項目を集めます。それが、自分のフォームになります。
type | 描画方法 |
|---|---|
field | フォームの入力項目です。nodeId、field、任意の allowedValues、任意の maxLength(テキスト入力の文字数の上限)を読み取ります。 |
node | ノード全体のデフォルトブロックです。カスタムフォームでは省略するか、そのノードのすべてのフィールドを描画します。ノード全体を公開したテキストノードにも、maxLength が付くことがあります。 |
output | 結果のライブプレビューです。フォームを構築している間は無視し、実行後に表示します。 |
richtext | 公開者が書いた、静的な Markdown です。そのまま描画します。 |
group | 独自の items を持つコンテナです。この中に入って処理します。グループはネストしません。 |
ステップ 2:各フィールドの型を調べる
inputItems は nodeId と field の組を教えてくれますが、テキスト、数値、選択肢といったフィールドの型までは教えてくれません。詳しく知るには、ノードタイプを調べます。
curl https://app.nodaro.ai/v1/nodes/generate-image{
"data": {
"type": "generate-image",
"label": "Generate Image",
"category": "ai-image",
"description": "...",
"outputType": "image",
"providers": ["nano-banana-pro", "gpt-image-2", "flux"], // shortened
"capabilities": ["supports-reference-image", "supports-negative-prompt"]
}
}すべてのノードの記述子が、完全な inputSchema を持っているわけではありません。ない場合は、次のルールを順番に適用して、コントロールを推測します。
- 入力項目に
allowedValuesがある場合:それらの選択肢を持つセレクトです。 snapshotNodes[i].data[field]の現在値が真偽値の場合:トグルです。- 現在値が数値の場合:数値入力です。フィールド名が
duration、intensity、strength、scale、temperatureのいずれかで終わる場合は、スライダーです。 - 現在値が文字列で、フィールド名が
prompt、description、text、content、caption、messageのいずれかの場合:複数行のテキストエリアです。 - 現在値が URL で、ノードタイプが
upload-で始まる場合:ファイルの公開 URL を送信する、ファイルアップロードです。 - それ以外:1 行のテキスト入力です。
次のフィールド名で、公開されるフィールドの大半をカバーできます。
| フィールド名 | コントロール | 備考 |
|---|---|---|
prompt、negativePrompt、text、description | テキストエリア | |
model、provider、voice、style、tone | セレクト | 選択肢は allowedValues または providers から取得します。 |
aspectRatio | セレクト | 通常は 1:1、16:9、9:16、4:3、3:4 です。 |
resolution | セレクト | 通常は 1K、2K、4K、または 720p、1080p、4k です。 |
quality | セレクト | 通常は medium と high です。 |
duration、nFrames、seed、temperature | 数値 | |
enableTranslation、addAudio、headless、loop | トグル | |
imageUrl、videoUrl、audioUrl、referenceImage | URL | 先にファイルをアップロードし、その URL を送信します。 |
MCP では、get_app_inputs がこの一部を型付けします。公開されたスライダーは、独自の min、max、step を持つ type: "number" として返ります。公開者が値のリストに限定したフィールドは、その options を持つ type: "select" として返ります。ノードのクイック設定のフィールドは、select、number、boolean のいずれかとして返ります。モデルとクイック設定のフィールドを参照してください。それ以外のフィールドは type: "text" として返るので、ノードを調べてください。スライダーのフラットな入力には、数値または数値の文字列を渡せます。
スライダーとトグル。 スライダーやトグルは、snapshotNodes[i].data[field] にあるノードの保存値から始まります。ノードに保存値がない場合、アプリはフィールドのデフォルト値(新しいノードに入る値)を表示します。実行がフィールドを送るのは、ユーザーが値を変更したあとだけです。それまでは、ノード自身の値が使われます。インターフェースでも同じようにしてください。コントロールにあらかじめ値を入れておき、ユーザーが変更したときだけフィールドを送ります。テキストから音声の音声設定は、数値または数値の文字列を受け付け、範囲外の値は範囲内に収められます。
モデルとクイック設定のフィールド
エディターでノードの下部バーにある設定は、どれもアプリで公開できます。モデルと、ほとんどの生成ノードでは解像度、長さ、アスペクト比、ドラフトなどの設定です。たとえば、動画から動画はモデル、解像度、ドラフトを公開でき、動画生成はモデルに加えて長さ、解像度、アスペクト比、ドラフトを公開できます。実行回数の設定である実行回数は、公開の対象になりません。
- キーはノード自体のデータフィールドです。
provider、v2vResolution、duration、draftなどです。値はinputOverrides[nodeId][field]に、ノードが保存する型で送ります。長さなら"8"ではなく8、ドラフトならtrueです。 - 固定のリストは強制されます。一部の設定は、ノードのほかの設定にかかわらず同じ値を提供します。ノードが提供するモデル、Suno のモデル、3D シーンのアスペクト比などです。リストにない値は
400 validation_error(Invalid value for provider: …. Allowed: …)で拒否されます。公開者はallowedValuesで、これらのリストをさらに制限できます。 - 範囲は強制されます。3D シーンの長さや動画マスクのしきい値のように、範囲内の任意の数値を受け付ける設定は、範囲外の数値を
400 validation_errorで拒否します。 - 一部の選択肢はモデルによって変わります。設定が提供する解像度、アスペクト比、長さは、ノードのモデルによって変わります。アプリのカードは、実行で使うモデルの選択肢を表示し、モデルが変わると、新しいモデルが受け付けない選択を切り替えます。フォームでも同じようにしてください。MCP の
get_app_inputsは、そのようなフィールドについてすべてのモデルの値を一覧にします。どのモデルで実行されるかは、snapshotNodes[i].data.provider、またはフォームが送る値でわかります。 - ドラフトは 480p でレンダリングされます。Seedance のモデルでは、ドラフトをオンにすると、アプリのカードは解像度も 480p に設定します。また、サーバーは送られた解像度にかかわらず、ドラフトを 480p でレンダリングします。
フィールドをクリアする
inputOverrides で null に設定したフィールドは、その実行でクリアされます。ノードは、そこに値がないものとして実行されます。null でも作成者の保存値でもなく、ノード自体のデフォルトが適用されます。アプリのカードは、選んだモデルにない設定に対してこの操作を行います。たとえば、動画から動画を解像度の設定がない Runway Aleph に切り替えると、解像度がクリアされます。カードは、ドラフトをオフにするときにもこの方法を使います。クリアしたフィールドが、allowedValues や固定のリストで拒否されることはありません。
MCP や SDK のフラットな入力では、null はノードに届く前に破棄されるので、ノードの保存値が適用されます。フィールドをクリアするには inputOverrides を使ってください。
Lottie のスロットフィールド
Lottie エンジンを使う モーショングラフィックス ノードは、色、テキスト、数値といった名前付きのスロットを、アプリの入力として公開できます。これらは、slot:primaryColor のように、field が slot: で始まるフィールド項目として現れます。ユーザーは、実行のたびにこれらを 0 クレジットで変更できます。アプリがスロットフィールドを公開している場合、すべての実行が公開済みのアニメーションを再利用し、スロットの値だけを入れ替えるためです。
| スロットの値 | コントロール | 送信する値 |
|---|---|---|
| 0 から 1 までの数値からなる RGBA 配列としての色 | カラーピッカー | "#00ff00" のような 16 進数の文字列 |
| 文字列 | テキスト入力 | その文字列 |
| 数値 | スライダー | その数値 |
スロットの値は、単純なノードのフィールドではなく、そのノードの motionPlan.slotValues の中にあります。生の inputOverrides を通じてスロットを設定するには、ノードの motionPlan 全体を、公開済みのプランのコピーで置き換え、その slotValues に変更内容を持たせます。色は RGBA 配列で指定します。slotValues の部分的なパッチでは、プランの残りの部分が失われてしまいます。Nodaro アプリと SDK は、これを自動で組み立てます。
{
"inputOverrides": {
"node-mg1": {
"motionPlan": {
// ...the published node's motionPlan, unchanged...
"slotValues": { "primaryColor": [0, 1, 0, 1], "nameText": "Acme Inc." }
}
}
}
}動画 URL の入力
動画 URLノードはアプリの入力にできます。そのため、アプリはエピソードを、アップロードの代わりにリンクとして受け取れます。get_app_inputs はこのフィールドを type: "video" として一覧表示し、フラットな入力はリンクそのものです。
{ "inputs": { "episode": "https://www.youtube.com/watch?v=VIDEO_ID" } }- 受け付けるもの。 動画があるページへのリンク、または動画への公開の
httpかhttpsのリンクです。動画のページへのリンクはダウンロードされ、それ以外のリンクはそのまま使われます。Web リンクでない値や、プライベートなアドレスを指す値は、何かが実行・課金される前に400 locked_fieldで拒否されます。アプリが公開していない動画 URLノードへのリンクも、同じように拒否されます。 - アプリのページでは。 動画のページへのリンクでは、フィールドの下にコンテンツ権利の確認欄が表示されます。アプリのユーザーは、チェックを入れて自分のリンクについての宣言を確認します。それまでは何も取得されません。リンクを変えると、チェックは外れます。リンクを読み取るのがコンテンツレシピだけの場合は、何もインポートされず、確認欄も表示されません。吹き替えはファイルを吹き替えるので、吹き替えが読み取るリンクは、ノードが見るリンクと同じようにダウンロードされます。
- 動画はサーバーがダウンロードします。 最初のノードが実行される前に、サーバーは、リンクより後ろのノードが読み取るものを取得します。動画を見るノードには動画を取得します。文字起こしと Suno カバーには音声だけを取得します。吹き替えには、自身のソースのリンクを吹き替える場合を除いて、動画を取得します。コンテンツレシピはページのアドレスを使うので、何も取得しません。
- 長い動画には範囲の指定が必要です。 Nodaro が先に動画の長さを読み取るサイトでは、4 分以上の動画や、長さを読み取れない動画は、一部分だけがダウンロードされます。その範囲を、
inputOverridesのノードに秒単位で指定してください:{ "<nodeId>": { "sectionStartSec": 600, "sectionEndSec": 1200 } }。範囲がない場合、実行は課金の前に拒否されます。ライブ配信も拒否され、ダウンロードに失敗した場合は、その理由とともに実行が拒否されます。 - 生のオーバーライド。
inputOverridesでは、リンクはノードのyoutubeUrlフィールドに入れます。 - コンテンツ権利。 サーバーによる取得は、リンクのインポートです。そのリンクとその実行についての確認を、
POST /v1/content-rights/confirmから得て、inputOverridesのノードのrightsConfirmationIdとして送ってください。1 件の確認で開けるのは 1 時間以内の 1 回のダウンロードだけなので、保存された入力に残ることはありません。確認のない実行が拒否されるのは、デプロイ環境が確認を必須としている場合だけです。コンテンツ権利を参照してください。 - 料金。 リンクより後ろで動画の長さによって課金されるステップは、その録音 1 分ごとの料金として
perMinuteCreditsに含まれます。
UGC 動画の入力
Nodaro Cloud で UGC 動画のノードを使って作ったアプリには、独自の入力が 2 つあります。クリエイターのカードと、動画の長さです。
クリエイターのカード。 UGC クリエイターの node 項目が、クリエイターのカードです。AIクリエイターか自分の写真、女性か男性を選び、自分の写真の場合は実行する人の写真をアップロードします。カードはノードの 3 つのフィールドに書き込むので、実行ではそれらをクリエイターのノード ID に送ります。
{
"inputOverrides": {
"<creator node id>": {
"source": "photo",
"gender": "woman",
"photoUrl": "https://example.com/runner.jpg"
}
}
}sourceは、AI クリエイターの場合はsampled、それ以外はphotoです。genderはwomanまたはmanです。photoUrlは公開の画像 URL で、自分の写真の場合だけ使います。
MCP の get_app_inputs は、このカードを 3 つのキーとして一覧表示します。source にはクリエイター自身のキー、そのキーに _gender と _photo_url を付けたキーです(どちらも省略可能)。アプリの実行は、クリエイターが選ばれるのを待ちません。1 人を抽選します。自分の写真の実行で、実行する人自身の写真が渡されない場合は、何かが実行・課金される前に 400 ugc_photo_required で拒否されます。
動画の長さ。 UGC スクリプトの動画の長さ(秒)(targetDurationSec)は、field 項目にできます。4〜300 秒のスライダーか、アプリが allowedValues で許可する長さ([15, 20, 25] など)です。inputOverrides では、数値として送ります。"20" ではなく 20 です。フラットな入力は、どちらも受け付けます。
UGC ノードのそれ以外のものは、実行では設定できません。 保持された結果、スクリプト、クリップなど、UGC ノードのそれ以外のフィールドは、400 locked_field で拒否されます。アプリでの UGC 動画を参照してください。
ステップ 3:フォームを構築する
// Adapt to your framework.
type FormField = {
nodeId: string
field: string
label: string // "aspectRatio" becomes "Aspect ratio"
control: "text" | "textarea" | "number" | "toggle" | "select" | "upload"
options?: Array<string | number | boolean>
defaultValue: unknown
}
async function buildForm(slug: string, baseUrl: string): Promise<FormField[]> {
const app = await fetch(`${baseUrl}/v1/app/${slug}`).then((r) => r.json())
const nodesById = new Map(app.snapshotNodes.map((n) => [n.id, n]))
const fields: FormField[] = []
const walk = (items) => {
for (const it of items ?? []) {
if (it.type === "group") walk(it.items)
if (it.type !== "field") continue
const node = nodesById.get(it.nodeId)
const current = node?.data?.[it.field]
fields.push(toFormField(it, node, current))
}
}
walk(app.snapshotSettings?.presentationSettings?.inputItems ?? [])
return fields
}- 値は、ラベルではなくノード ID をキーにします。実行のボディは
{ "inputOverrides": { "<nodeId>": { "<field>": value } } }です。 - Nodaro は
allowedValuesを強制します。リストにない値は400 validation_errorで拒否されます。クイック設定のフィールドの固定のリストにない値も同様です。 - Nodaro は
maxLengthを強制します。上限より長いテキストは400 input_too_longで拒否されます。テキストエリアにmaxlengthを付け、文字数カウンターを表示してください。音声の入力では、アプリの料金はこの上限を前提にしています。 - Nodaro はピッカーの制限を強制します。公開者は、舞台設定、ムード、人物などのピッカーを、カタログの一部に限定できます。限定は
snapshotSettings.presentationSettings.cardMeta[nodeId]にあります。単一次元のピッカーはpickerAllowedValuesを使い、複数次元のピッカーはpickerAllowedValuesByField({ field: [ids] })を使います。リストにない値は、API での実行を含め、アプリのすべての実行で400 validation_errorで拒否されます。選択を取り消すには、フィールドを省くか、空の値を送ります。カタログのデフォルト値は送らないでください。 - デフォルト値は、
snapshotNodes[i].dataからあらかじめ入力しておきます。何も変更しないユーザーでも、意味のある実行になるようにするためです。 estimatedCreditsを表示し、実行前にユーザーが料金を把握できるようにします。perMinuteCreditsやperItemCreditsが 0 でない場合、料金は録音の長さやリストの項目数に応じて増えます。固定の部分に、それらの部分を加えて表示してください。estimatedCreditsには最終レンダリングの分も含まれ、runEstimatedCreditsとその 1 分ごと・項目ごとの部分は、実行だけの料金です。maxEstimatedCreditsがある場合、料金はユーザーの選択によって変わります。「5 から最大 9」のように範囲で表示してください。「最大」は、公開されたすべてのフィールドにわたって実行にかかりうる最高額です。公開者が許可した値が設定されている場合はその値、各モデル自体の選択肢、ユーザーが渡すリファレンスクリップの最長の長さで計算されます。この範囲が導入される前に公開されたバージョンには、もう一度公開されるまでmax*フィールドがありません。estimatedCreditsIsEstimateがtrueの場合、料金には LLM の呼び出しの見積もりが含まれます。その呼び出しは実際に使ったトークンに応じて課金されるので、料金は5ではなく~5と表示してください。maxRunsPerUserPerDayが設定されている場合は、「本日は 5 回中 2 回使用済み」のように、1 日の上限を表示し、予期しない429を避けます。
ステップ 4:実行を開始してポーリングする
トークンを使って実行を開始します。
curl -X POST https://app.nodaro.ai/v1/app/<slug>/run \
-H "Authorization: Bearer $NODARO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"inputOverrides": {
"node-abc": { "prompt": "a cat astronaut", "aspectRatio": "16:9" }
}
}'応答は 202 Accepted です。
{ "executionId": "exec-uuid", "runId": "run-uuid", "status": "pending" }| 任意のボディフィールド | 内容 |
|---|---|
version | アプリの指定したバージョンを実行します。デフォルトは最新版です。 |
inputs | アプリの入力を、入力名から値へのフラットなマップとして渡します。SDK と CLI が送る形式です。inputOverrides はフィールドごとに inputs の上に適用され、両方が同じフィールドを設定している場合は inputOverrides が優先されます。公開されたスライダーのように数値のフィールドは、数値または数値の文字列を受け取ります。"0.4" は 0.4 として届きます。 |
runId | 実行を、以前に作成した下書きの実行に紐付けます。最初の構築では無視してかまいません。 |
inputOverrides は、promptPrefix のような、アプリが公開していないノードのフィールドも設定できます。プロンプトの前後のテキストを参照してください。ただし、送信系のノードがデータを送信または取得する宛先(Webhook 出力のアドレスなど)や、サブワークフローノードが実行するワークフローは、決して変更できません。そのような実行は 400 locked_field で拒否されます。
作成者の手数料があるアプリ。 Nodaro Cloud では、作成者の手数料があるアプリの実行は、何かが書き込まれたり実行されたりする前に、実行する人の残高と照らし合わされます。残高は、アプリの実行の表示価格と手数料をまかなえる必要があります。
- 手数料は、それが適用される表示価格に、固定の手数料とその価格に対する割合を足した額で、クレジットの整数に切り上げられます。
- 表示価格が 0 でも、固定の手数料は全額数えられます。
- 残高でまかなえない実行は、
402 insufficient_creditsで拒否されます。メッセージには、手数料を含む実行の料金、手数料、残高が示されます。 - 自分のアプリを実行する作成者は、手数料を払わず、照合もされません。
組織のワークスペースが支払う実行では、組織がアプリを承認している場合、手数料はワークスペースが支払います。そうでない場合、手数料は実行する人が支払います。
- 承認済みのアプリの実行は、予算の余裕分で表示価格と手数料をまかなえない場合、ワークスペース自体の
402 budget_exceededで拒否されます。 - 組織が承認していないアプリは、実行する人自身の残高で手数料をまかなえない場合、
402 insufficient_creditsで拒否されます。実行そのものは、この場合もワークスペースが支払います。
手数料は実行の完了後に精算され、支払う人がその時点で持っている分だけが徴収されます。つまり、実行する人の残高(手数料のために 0 を下回ることはありません)か、ワークスペースの予算の余裕分が上限です。作成者には、徴収された額がそのままクレジットされます。残りは誰からも徴収されず、誰にも支払われません。作成者の収益の記録には、求められた手数料(flatFee、percentFee)と、徴収された額(totalEarned)が並んで残ります。ワークスペースを参照してください。
続けて、実行をポーリングします。
curl https://app.nodaro.ai/v1/app/<slug>/runs/<runId> \
-H "Authorization: Bearer $NODARO_API_TOKEN"{
"id": "run-uuid",
"executionId": "exec-uuid",
"status": "pending|running|completed|failed",
"creditsUsed": 0, // the run's total, every attempt included
"thumbnailUrl": null, // set when the run completes
"execution": {
"status": "pending|running|completed|failed",
"nodeStates": {
"node-abc": {
"status": "completed",
"output": { // the shape depends on the node's outputType
"url": "https://.../result.png",
"imageUrl": "...",
"videoUrl": "...",
"audioUrl": "...",
"resultUrl": "...",
"text": "..."
}
}
},
"totalNodes": 5,
"completedNodes": 5,
"failedNodes": 0,
"totalCreditsUsed": 5, // this attempt's own
"errorMessage": null,
"completedAt": "2026-05-07T..."
}
}- 2 秒ごとを目安にポーリングします。
execution.statusがcompletedまたはfailedになったら止めます。 - 実行中は、
totalNodesに対するcompletedNodesとして、進行状況を表示します。 - 失敗した場合は、
execution.errorMessageを表示します。
実行の所有者が変更できるのは、PATCH /v1/app/{slug}/runs/{runId} による name、inputValues、hiddenNodes、nodeStates だけです。サーバーはそれ以外のフィールドを無視し、この 4 つのどれも指定しない PATCH には 400 bad_request を返します。
実行のビューは、実行の結果に対するあなた自身の編集を nodeStateEdits として含みます。これは、PATCH が nodeStates で設定するマップです。PATCH はこのマップ全体を置き換えます。すでに保存されているすべての編集を自分の編集とマージして送ってください。送らなかった編集は失われます。
ステップ 5:結果を表示する
メインの結果は、thumbnailNodeId が指すノードの出力です。その URL は execution.nodeStates[thumbnailNodeId].output から読み取り、url、imageUrl、videoUrl、audioUrl、resultUrl の順に試し、最後に、テキストの結果については text を試します。text はリンクではなく、テキストとして表示します。
GET /v1/nodes/{type} から得られる、ノードの outputType に応じて描画します。
outputType | 描画方法 |
|---|---|
image | 画像 |
video | コントロール付きの動画プレーヤー |
audio | コントロール付きの音声プレーヤー |
text | 整形済みテキストまたは Markdown |
data | JSON ビューアー、または中身を解釈しないデータ |
thumbnailNodeId が null の場合は、ワークフローの順序で最後のノードを使うか、空でない出力をすべて表示します。
実行の最終版をレンダリングする
アプリの EDL 適用のレンダリングがプレビューを作ると、アプリのページはそれに対して最終レンダリングを表示します。コードからは、POST /v1/app/{slug}/runs/{runId}/render-final に { "renderNodeId": "<render node id>" } を送ります。サーバーは、そのレンダリングをこの実行に限り Final で行い、その後のすべてのノードを 1 回実行します。レンダリングより前のものは、実行も請求もされません。
応答は 202 で、{ executionId, runId, status: "pending" } です。8 文字以上の Idempotency-Key ヘッダーを付けると、同じリクエストの再試行には "deduped": true 付きの 200 が返され、何も開始されません。
- 支払う人。最終版は、アプリを実行する人に、ノード自体の料金で、アプリの実行とは別の 2 回目の実行として請求されます。アプリの作成者の手数料はかかりません。最終版は実行履歴に行を追加せず、アプリの 1 日の実行上限にも数えられません。
- レビューが反映されます。上の
PATCHで実行に保存した編集プランのレビューが、最終版に適用されます。 - 結果が表示される場所。最終版に結果が出ると、
GET /v1/app/{slug}/runs/{runId}は、それをプレビューの状態の上にexecution.nodeStatesで表示し、それぞれに"fromRenderFinal": trueを付けます。実行はfinalExecution: { id, status, completedNodes, totalNodes, errorMessage, completedAt, creditsUsed }も含み、最終版を求めていない場合はnullです。実行自体のcreditsUsedは、アプリの実行の値のままです。 - エピソードを引き締めるノードも同じ方法で仕上げます。エピソードを引き締めるノードのうち、レンダリング前に確認がオンのものは、自分でプレビューを持つので、ノード自体を
renderNodeIdに指定します。最終版は、エピソードを Final で、その編集に対するレビューを反映してレンダリングし、続いて字幕と BGM を加えます。エピソードを引き締めるの手数料はかかりません。その後のノードは、アプリの実行ですでにプレビューに対して実行されていますが、最終版でもう一度実行されます。仕上げられるのはプレビューのテイクだけです。Final のテイクや、リストの項目ごとに 1 回ずつ実行されたテイクは、render_final_not_previewで拒否されます。 - 失敗した最終版は表示されません。
finalExecutionがそのstatusとerrorMessageを報告し、ビューはプレビューをもう一度表示します。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | not_a_render | renderNodeId が、アプリのレンダリングノードではありません。 |
| 400 | preview_render_nested | アプリがコンポーネントです。 |
| 402 | insufficient_app_credits | クレジットが最終版の料金に足りません。 |
| 404 | not_found | このアプリに、その実行が見つからないか、あなたのものではありません。 |
| 409 | continuation_not_completed | 実行がまだ実行されていない下書きか、完了していません。 |
| 409 | already_running | この実行の最終版が、まだレンダリング中です。その ID は executionId にあります。 |
| 503 | run_finals_unavailable | 実行の以前の最終版を、今は読み取れませんでした。もう一度試してください。何も開始されていません。 |
どの拒否も、何かが書き込まれたり請求されたりする前に行われます。
失敗した実行を再試行する
失敗したアプリの実行は、最初からやり直すのではなく、止まった所から続けます。POST /v1/app/{slug}/runs/{runId}/resume を送信します。これは、アプリのページの再試行ボタンと同じです。実行が完了しなかったステップだけが、もう一度実行されます。完了したステップは、すべて結果を引き渡し、再び請求されることはありません。失敗した UGC クリップは、仕上がっていないクリップだけをレンダリングします。
- 先に
{ "dryRun": true, "version": <n> }を送信します。応答は200で、steps(もう一度実行されるステップ)、estimatedCredits(作成者の手数料を含む、再試行で請求される見込みの額)、reusedClips、sufficient、availableを含みます。sufficientは、残高とアプリ用クレジットで再試行をまかなえるかどうかを示します。appCreditsAllowanceは、アプリ用クレジットが原因で再試行できない場合にだけ含まれます。その場合、再試行はinsufficient_app_creditsで拒否されます。何も開始されません。 - ステップと料金をユーザーに表示します。
- ユーザーが同意したら、
dryRunを除いた同じボディを送信します。応答は202で、{ executionId, runId, status: "pending", nodeIds }です。ステップ 4 と同じように、実行をポーリングします。
- 実行自体のバージョンと入力。再試行は、その実行が使ったアプリのバージョンを、その実行が適用した入力で実行します。再試行自体は入力を受け取りません。インターフェースが実行するバージョンを
"version"に入れて送信してください。省略すると、アプリの最新バージョンが使われます。 - 代わりに最初からやり直す。別の入力で、またはアプリの現在のバージョンで実行するには、実行を最初からやり直します。
POST /v1/app/{slug}/runに"runId": "<runId>"を付けて送信します。すべてのステップがもう一度実行され、再び請求されます。 - 再試行は一度に 1 回。同時に 2 回押しても、開始される再試行は 1 回です。2 回目の応答は
"deduped": true付きの200です。その再試行が保留中の間に押すと、409 already_runningが返され、その再試行が示されます。再試行をさらに再試行すると、最新の再試行が完了した所から続きます。 - 作成者の手数料は 1 回だけ精算されます。対象は、再試行で実行される部分です。アプリの実行と同じく、再試行には実行する人のアプリ用クレジットが使われます。
- 試行をまたいだクレジット。実行の
creditsUsedは、すべての試行の合計です。失敗した実行が使った分と、各再試行が使った分を合わせた額です。再試行の実行中も、最新の値に更新されます。execution.totalCreditsUsedは、現在の試行だけの使用額です。実行を最初からやり直すと、新しい合計が始まります。 - 分析では、1 回の実行は 1 回として数えます。アプリの分析では、実行は最後に終わった試行の結果で数えられます。失敗したあと再試行で完了した実行は、成功した実行 1 回です。再試行で実行の数は増えません。各試行のクレジットは、その試行が終わった日に数えられます。
- SDK、CLI、MCP から。SDK では
client.apps.resume、CLI ではnodaro apps run-retry、MCP サーバーではretry_app_runで再試行を呼び出します。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | validation_error | 実行 ID かボディの形式が正しくないか、コンポーネントの実行です。コンポーネントの実行は、それを呼び出した実行によって続けられます。 |
| 400 | continuation_workflow_mismatch / continuation_version_mismatch | 実行のワークフロー実行が、別のワークフロー、または別のバージョンを実行しました。まれなケースです。実行を最初からやり直してください。 |
| 400 | locked_field | 実行が適用した入力が、アプリで実行する人が設定できないフィールドを設定しています。 |
| 400 | preview_review_required | 再試行がプレビューで止まりますが、アプリのページの印がありません。 |
| 402 | insufficient_app_credits / insufficient_credits | 実行する人のアプリ用クレジットまたは残高が、再試行の料金に足りません。 |
| 404 | not_found | このアプリに、自分のその実行がありません。 |
| 404 | continuation_not_found | その実行のワークフロー実行が、自分のものではありません。 |
| 409 | app_run_version_unavailable | 実行が使ったバージョンが、もう利用できません。実行を最初からやり直してください。 |
| 409 | app_run_version_changed | アプリのバージョンが、実行のバージョンと異なります(appVersion、runVersion)。実行を最初からやり直すか、実行のバージョンを送信してください。 |
| 409 | continuation_not_failed | 実行が失敗していません。完了したか、停止されました。最初からやり直してください。 |
| 409 | already_running | 実行がまだ進行中(executionId)か、別の場所でもう一度開始されました。 |
| 409 | continuation_subset_required | 実行のすべてのステップが完了しています。再試行するものはありません。アプリがステップを 1 つも実行しない場合、ステータスは 400 です。 |
| 503 | billing_unavailable | ワークスペースの実行で、課金が一時的に利用できません。少し待ってから、もう一度お試しください。 |
再試行が 409 で拒否されたら、実行を最初からやり直すことを提案してください。
実行を削除する
curl -X DELETE https://app.nodaro.ai/v1/app/<slug>/runs/<runId> \
-H "Authorization: Bearer $NODARO_API_TOKEN"削除は、実行をユーザーのアーカイブに移し、{ "success": true, "archived": true } で応答します。何かが破棄されることはありません。誤った実行を削除する自動化があっても、ユーザーのデータが失われることはありません。実行の復元と完全な削除は、Nodaro アプリでしかできないため、自分の連携では、どちらも試みるべきではありません。
認証する
実行には、必ずベアラートークンが必要です。実行の所有者と支払い者が誰であるべきかによって、種類を選びます。
| 構築しているもの | 使うもの |
|---|---|
| 個人用ツール、代理店向けダッシュボード、社内の自動化 | 個人用 API トークン。 |
| 顧客がそれぞれ自分の Nodaro アカウントを接続する SaaS | OAuth。 |
| 匿名の訪問者のためにアプリを実行する、公開ツール | 個人用 API トークン。支払うのは自分なので、訪問者ごとの実行回数は自分の側で制限します。 |
個人用 API トークン。自分のアカウントが、すべての実行を所有し、料金を支払います。設定 › APIトークンを開き、トークンを作成でトークンを作成します。表示されたトークンをその場でコピーし、サーバーのシークレットとして保存します。トークンは、取り消すまで有効です。認証を参照してください。
OAuth。各ユーザー自身のアカウントが、それぞれの実行を所有し、料金を支払います。開発者アプリを登録し、workflows:execute と jobs:read のスコープを添えて、ユーザーを同意画面に送ります。workflows:execute は、実行の開始、再試行、最終版のレンダリング、名前の変更と削除に使います。jobs:read は、実行のポーリングと一覧表示に使います。これらには、workflows:execute または assets:read だけでも使えます。GET /v1/app/{slug} でアプリを読み込むには、スコープは必要ありません。自分のサーバーで、認可コードを、90 日間有効なアクセストークンと交換します。呼び出しが 403 insufficient_scope を返す場合は、より広いスコープで、ユーザーにもう一度同意画面を通ってもらいます。
トークンはサーバーに置く
トークンは、決してブラウザーに渡してはいけません。バンドラーは、VITE_ や NEXT_PUBLIC_ のプレフィックスが付いた環境変数を、配布する JavaScript にそのまま埋め込みます。そうなると、開発者ツールを使える人なら誰でもトークンを読み取り、あなたのクレジットを使えてしまいます。
[Browser] --HTTPS--> [Your server or edge function] --HTTPS--> Nodaro API
(holds NODARO_API_TOKEN)| スタック | トークンの置き場所 |
|---|---|
| Supabase を使う Lovable | Supabase Edge Function のシークレットです。supabase secrets set NODARO_API_TOKEN=... |
| Next.js | process.env.NODARO_API_TOKEN を使う、サーバールートハンドラーです。NEXT_PUBLIC_ プレフィックスは付けません。 |
| SvelteKit、Remix、Nuxt | サーバー専用の環境変数です。SvelteKit の $env/static/private などです。 |
| Vercel または Netlify のエッジ関数 | クライアントに公開されない、プロジェクトの環境変数です。 |
| Cloudflare Worker | Worker のシークレットです。wrangler secret put NODARO_API_TOKEN |
ブラウザーのコードは自分のサーバーとしか通信しないため、自分のドメインを Nodaro の許可するオリジンに追加する必要はありません。OAuth を使ってブラウザーから Nodaro を呼び出す場合は、開発者アプリの許可するオリジンに、自分のオリジンを登録してください。
エラー
エラーは { "error": { "code": "...", "message": "..." } } の形をしています。
| ステータス | コード | 原因 | 対処 |
|---|---|---|---|
400 | validation_error | 不正な形式の inputOverrides、allowedValues やピッカーの許可リストにない値、または不正な形式のスラッグです。 | リクエストボディを修正します。 |
400 | input_too_long | テキストの入力が、フィールドの maxLength より長くなっています。 | テキストを、その項目が示す上限まで短くします。 |
400 | locked_field | オーバーライドが、送信系のノードの宛先(Webhook 出力のアドレスなど)か、UGC ノードが実行から受け取らないフィールドを指定しています。 | それを取り除きます。送信先と取得先は、アプリが決めます。UGC ノードが受け取るのは、クリエイターのカードのフィールドと動画の長さだけです。 |
400 | ugc_photo_required | UGC クリエイターが自分の写真に設定されていて、実行で実行する人自身の写真が渡されていません。 | 実行する人の写真を求めるか、カードをAIクリエイターに切り替えます。 |
400 | clone_recordings_required | テキストから音声またはテキストから会話ノードが Gemini 3.8 Flash でボイスをクローンしますが、実行で実行する人自身の録音が渡されていません。 | 実行する人の 2 つの WAV 録音を求めます:inputOverrides[<node>].replica、または会話の場合はその speakers です。 |
400 | clone_consent_required | クローンしたボイスの同意が、その録音に対する実行する人自身の記録ではありません。 | 実行する人に POST /v1/voice-clone/consent で同意してもらい、その記録を replicaConsent として渡します。 |
400 | clone_model_unsupported | 実行がクローンしたボイスに使うモデルは、ボイスをクローンできません。公開したモデルカードや、接続したキャラクターのボイスで起こります。 | ノードを Gemini 3.8 Flash のままにします。 |
400 | clone_not_fillable | アプリが、サブワークフローまたはコンポーネントの中でボイスをクローンしていて、実行する人の録音がそこに届きません。 | ボイスをクローンするノードを、アプリ自身のワークフローに移します。 |
401 | unauthorized | トークンがないか、期限切れか、取り消されています。 | 新しいトークンを作成するか、もう一度認可します。 |
402 | insufficient_app_credits | トークンに紐づくアカウントのクレジットが不足しています。 | クレジットを追加するか、プランを変更します。 |
402 | insufficient_credits | UGC 動画を作るアプリで、クリップのレンダリング中に動画が必要とし得る分を、残高でまかなえません。 | クレジットを追加するか、短い動画を作ります。 |
402 | insufficient_credits | 作成者の手数料があるアプリで、アプリの実行の表示価格と手数料を残高でまかなえません。組織が承認していないアプリのワークスペースでの実行では、実行する人自身の残高で手数料をまかなえません。作成者自身の実行は照合されません。 | クレジットを追加します。 |
402 | budget_exceeded | 組織が承認した、作成者の手数料があるアプリのワークスペースでの実行で、ワークスペースの予算でアプリの実行の表示価格と手数料をまかなえません。 | ワークスペースの管理者に、余裕分を増やすよう依頼します。 |
403 | insufficient_scope | OAuth トークンに、missingScope に示されたスコープがありません。 | より広いスコープで、もう一度認可します。 |
404 | not_found | スラッグまたは実行が存在しないか、アプリが無効化されているか、実行の実行記録がその実行の所有者のものではありません。 | スラッグを確認し、「アプリを利用できません」と表示します。 |
429 | rate_limit_exceeded | アプリの、ユーザーあたりの 1 日の実行上限に達しています。 | 「本日の上限に達しました」と表示します。 |
500 | internal_error | サーバー側の不具合です。 | 少し待ってから 1 回再試行し、それでも解決しない場合は報告します。 |
参考テンプレート
アプリをプロキシする Supabase Edge Function
// supabase/functions/nodaro-run/index.ts
import { serve } from "https://deno.land/std@0.224.0/http/server.ts"
const BASE = Deno.env.get("NODARO_BASE_URL")! // for example https://app.nodaro.ai
const TOKEN = Deno.env.get("NODARO_API_TOKEN")! // ndr_...
const SLUG = Deno.env.get("NODARO_APP_SLUG")! // my-cool-app
serve(async (req) => {
const url = new URL(req.url)
// Public probe: no token is sent, because the endpoint is public.
if (req.method === "GET" && url.pathname.endsWith("/schema")) {
const r = await fetch(`${BASE}/v1/app/${SLUG}`)
return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
}
// Start a run.
if (req.method === "POST" && url.pathname.endsWith("/run")) {
const { inputs } = await req.json()
const r = await fetch(`${BASE}/v1/app/${SLUG}/run`, {
method: "POST",
headers: {
"Authorization": `Bearer ${TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ inputOverrides: inputs }),
})
return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
}
// Poll a run.
const m = url.pathname.match(/\/runs\/([0-9a-f-]{36})$/)
if (req.method === "GET" && m) {
const r = await fetch(`${BASE}/v1/app/${SLUG}/runs/${m[1]}`, {
headers: { "Authorization": `Bearer ${TOKEN}` },
})
return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
}
return new Response("Not found", { status: 404 })
})ブラウザーのコード:読み取り、実行、ポーリング
// 1. On mount: read the schema and build the form (steps 1 to 3).
const schema = await fetch("/functions/v1/nodaro-run/schema").then((r) => r.json())
const inputItems = schema.snapshotSettings?.presentationSettings?.inputItems ?? []
// 2. On submit: send the values keyed by node id.
const start = await fetch("/functions/v1/nodaro-run/run", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
inputs: { "node-abc": { prompt: form.prompt, aspectRatio: form.aspectRatio } },
}),
}).then((r) => r.json())
// 3. Poll every 2 seconds until the run ends.
let last = start
while (last.status !== "completed" && last.execution?.status !== "completed"
&& last.status !== "failed" && last.execution?.status !== "failed") {
await new Promise((res) => setTimeout(res, 2000))
last = await fetch(`/functions/v1/nodaro-run/runs/${start.runId}`).then((r) => r.json())
}
// 4. Read the result.
const out = last.execution?.nodeStates?.[schema.thumbnailNodeId]?.output ?? {}
const heroUrl = out.url ?? out.imageUrl ?? out.videoUrl ?? out.audioUrl ?? out.resultUrl
const heroText = out.textこのテンプレートでは、ブラウザーがノード ID をキーにした値を送信し、エッジ関数がそれを inputOverrides として渡します。
インターフェースのコードを生成する前のチェックリスト
GET {BASE}/v1/app/{slug}が、入力スキーマとデフォルト値を返した。inputItems内の各nodeIdについて、snapshotNodesからそのtypeがわかっている。- 各ノードタイプについて、
GET {BASE}/v1/nodes/{type}から、カテゴリー、outputType、モデルがわかった。 - ステップ 2 のルールで、フォームフィールドの一覧を構築した。
- 結果のノード(
thumbnailNodeIdまたは最後のノード)と、そのoutputTypeがわかっている。 - 個人用 API トークンか、開発者アプリの認証情報を持っている。
- シークレットは自分のサーバーに置かれている。
よくある質問
Nodaro のミニアプリを、自分のサイトに埋め込むには、どうすればよいですか?
「ミニアプリ」を開き、「マイミニアプリ」を選んで、アプリのカードにある「埋め込み」をクリックします。「埋め込みを許可するドメイン」に自分のサイトのドメインを追加し、「埋め込みコードをコピー」をクリックして、iframe を自分のページに貼り付けます。ドメインを 1 つ以上追加するまで、埋め込みはブロックされます。
ミニアプリ用の独自のインターフェースを構築するには、どのエンドポイントが必要ですか?
入力を調べるための GET /v1/app/{slug} と GET /v1/nodes/{type} で、どちらも公開エンドポイントです。続いて、実行を開始するための POST /v1/app/{slug}/run と、それをポーリングするための GET /v1/app/{slug}/runs/{runId} を使います。この 2 つにはトークンが必要です。
ミニアプリの実行が終わると、Nodaro は自分のサーバーを呼び出しますか?
いいえ。ミニアプリの実行からのコールバックはありません。ステータスが completed か failed になるまで、2 秒ごとを目安に実行をポーリングしてください。
埋め込まれたミニアプリの実行の料金は、誰が支払いますか?
実行の名義となるアカウントです。個人用 API トークンを使う場合は、自分のアカウントがすべての実行の料金を支払います。OAuth を使う場合は、各ユーザー自身のアカウントが、それぞれの実行の料金を支払います。
API 経由で、ミニアプリの実行を削除できますか?
はい。実行に対する DELETE は、それをアーカイブし、ユーザーは Nodaro アプリでそれを復元できます。復元と完全な削除は、Nodaro アプリでしかできません。
関連ページ
埋め込み
アプリ(ミニアプリ)
OAuth アプリ
認証
TypeScript SDK
最終更新