ノード
POST /v1/<node-type> で、任意の Nodaro ノードを実行します。ノード、モデル、ピッカーの値を調べ、リファレンスや演出の ID でプロンプトを調整する方法も説明します。
ノードの実行は、ワークフローを組まずに、Nodaro のノードを 1 つだけ直接呼び出します。POST /v1/<node-type> に、ノードの設定をボディとして送信します。generate-image や generate-video から text-to-speech まで、すべての生成ノードがこの形に従っており、検出用のエンドポイントで、どのノード、モデル、設定が存在するかを調べられます。ほとんどのノードの実行は非同期です。レスポンスは jobId で、結果ができるまでポーリングします。
ノードを実行する
ノードタイプのルートは、POST /v1/ の後にそのタイプを付けたもので、ボディはノードの設定を JSON にしたものです。
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でジョブをポーリングします。ジョブを参照してください。 - 画像と動画の生成では、
adjustmentsが加わることがあります。これは、選んだモデルのためにサーバーが補正した設定の一覧です。generate-videoとgenerate-imageでは、warningsが加わることもあります。パラメーターの補正を参照してください。 combine-textなどのインラインノードは、jobIdを返さずに、完全な結果をすぐに返します。web-scrapeなどのスクレイパーも、すぐに応答します。レスポンスには、履歴のためのjobIdと、データ自体の両方が含まれます。
生成は、開始時にクレジットを確保します。アカウントがその実行分をまかなえない場合、呼び出しは 402 insufficient_credits を返します。
パスが長いノード
言語モデルを呼び出すテキストノードの多くは、同じ POST /v1/<node-type> の規則に従います。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) と CLI の nodaro nodes run は、これらのノードタイプをそれぞれ専用のルートに自動で POST します。ノードを実行するを参照してください。
言語モデルのルートは、2 つの任意のフィールドを受け付けます。
reasoningEffort:モデルによって、none、low、medium、high、xhigh、maxのいずれかです。省略するか、そのモデルが対応していない段階を指定すると、モデル自体のデフォルトになります。推論の強度そのものに料金はありません。呼び出しは使ったトークンに応じて課金されるため、強度を上げると、書かれる推論の分だけ高くなります。Claude モデルでは、どの推論の段階でも、呼び出しが Anthropic 自身の API 上で、そのレーンの単価で実行されます。advancedMode: true:Gemini モデルと Claude モデルです。リクエストはモデル開発元自身の API 上で実行されます。これは、temperature、maxTokens、推論の全範囲が効く唯一の経路です。呼び出しは、そのレーンのトークンあたりの単価で課金されます。この経路がないモデルは、400 advanced_mode_unsupportedを返します。モデル自体のプロバイダーがリクエストを受け付けられない間は、リクエストはデフォルトの経路で実行されず、拒否されます。デフォルトの経路では、これらの設定が効かないためです。課金の前なら400 advanced_mode_unavailableが、呼び出しの途中なら502 advanced_mode_unavailableが返されます。途中での拒否は、プロバイダーが試行に課金していなければ返還されます。モデルをデフォルトの経路で実行するには、詳細モードをオフにしてください。
POST /v1/llm-chat/generate では、モデルはリファレンス動画を 1 秒あたり 1 フレーム読み取ります。referenceVideoFps(0 より大きく 24 以下)を指定すると、より多くのフレームを読み取ります。これには Gemini モデルで advancedMode: true が必要で、そうでない場合は 400 video_fps_needs_advanced_mode が返されます。フレームが多いほど、入力トークンも増えます。テキスト生成 - あらゆる LLMを参照してください。
describe-to-picker は、同じリクエストの中で結果を返します。また、回答をサーバー送信イベントとしてストリーミングすることもできます。説明をピッカーへを参照してください。generate-script のフィールドは、脚本生成にあります。
例:画像を生成する
ジョブを開始する
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"
}'{ "jobId": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10" }import { createClient, StaticTokenAuth } from '@nodaro/sdk'
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',
})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 秒ごとにジョブのステータスを確認します。
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 も持ちます。
{
"data": {
"id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
"status": "completed",
"progress": 100,
"output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
"error_message": null
}
}SDK と CLI は、代わりにポーリングを行えます。
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)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 | ジョブが開始される前に、実行が拒否された場合です。 |
ModelUnavailableError | このデプロイ環境がモデルを提供していないか、管理者がモデルをオフにした場合です。別のモデルを選んでください。 |
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 でよく使う設定です。各設定がエディターで何を行うかは、画像生成を、各モデルが対応している内容は、画像モデルを参照してください。
プロパティ
型
マスクを使った編集やリファインの料金は、そのモデルでの新規生成と同じです。
GPT Image 2.6 Flare と Sunburst では、outputFormat で PNG の代わりに JPEG、WebP、512×512 のアニメーション GIF、または SVG の図を書き出せます。GIF は aspectRatio と resolution を無視し、gif または svg でのマスクは 400 で拒否されます。完了したジョブは、ファイルの種類を output_data.imageMimeType で示します。各形式の設定がどう補正されるかはパラメーターの補正を、料金は画像生成の形式を参照してください。
/v1/generate-image は、要求したものが送られなかった場合に、{ code, message } のリストである warnings を返すことがあります。現在のコードは moodboard_images_not_sent だけです。ムードボードの画像の一部が、モデルのリファレンスの上限に収まらなかったことを示します。実行はそのまま進み、ジョブは同じ警告を input_data.warnings に保持します。
プリセットを適用する
POST /v1/generate-image は presetId を受け付けます。generate-image/cinematic-still のような組み込みの ID か、自分のプリセットの uuid です。組み込みの ID は、トークン不要の GET /v1/node-presets/factory?nodeType=generate-image で一覧表示できます。ルートは、エディターが画像生成ノードに適用するのと同じ方法でプリセットを適用するので、ジョブはエディターの実行が送るものと同じになります。
- プリセットのプロンプトと、その前後のテキスト(
promptPrefixとpromptSuffix)。 {name || default}のプレースホルダーは、デフォルトで埋められます。- その
styleは、プロンプトに組み込まれます。 - そのネガティブプロンプトは、対応するモデルではネイティブに送られ、それ以外のモデルではプロンプトに 「Avoid:」(避けるもの)の行として追加されます。
- その設定と、プリセットが設定していないものについてはエディターのデフォルト(モデル
gpt-image-2、比率16:9)。モデルと料金は、エディターと同じです。
送ったフィールドは、適用したノードを編集したときと同じく、プリセットより優先されます。prompt はプリセットのプロンプトを置き換え、その前後のテキストで囲まれます。provider、aspectRatio、resolution、quality、negativePrompt、style などの設定は、プリセットの値を置き換えます。リファレンス、sessionId、origin は保持されます。
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"presetId": "generate-image/logo-wordmark", "presetVariables": {"BRAND": "Acme"}}'- デフォルトのないプレースホルダー(
{BRAND}など)には、presetVariablesで値を指定する必要があります。指定しないと、ルートはcode: "preset_variables_required"とtokens: ["BRAND"]付きの400を返します。 - 不明な
presetIdには、404 preset_not_foundが返されます。 - クレジットの確認では、プリセットを適用した後のリクエストの料金が計算されます。
presetIdとpresetVariablesは、どちらもジョブに保存されません。 - 写真から作るプリセットは、
minReferencesが 0 より大きくなっています。その枚数の画像をreferenceImageUrlsで送ってください。プリセットを参照してください。 - プリセットは
countやmodelsと組み合わせられます。次のセクションを参照してください。 - プリセットでは、自分のパレットやムードボードを使えません。その
directionがpalette:<id>やmoodboard:<id>を指定している場合は、自分で送ったものでもプリセットに保存されたものでも、何かが作成または請求される前に、ルートはキーを示すfield付きの400 validation_errorを返します。
1 回の呼び出しで複数の画像
POST /v1/generate-image は、複数の画像を一度に作れます。
count(1〜4)は、1 つのモデルでその枚数の画像を作ります。各画像は、それぞれ独立したジョブです。models(providerと同じ ID で、2〜4 個の異なる画像モデル)は、providerの代わりに使い、同じリクエストを各モデルに送ります。各モデルの設定は、1 回の呼び出しと同じくそのモデルに合わせて調整され、補正はモデルごとに報告されます。- 両方を指定した場合、
countはモデルごとの数です。models: ["gpt-image-2", "flux-2-max"]とcount: 2では、4 枚の画像が作られます。1 回のリクエストで作れる画像は、最大 8 枚です。
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0f8e6c1a-try-1" \
-d '{"prompt": "a lighthouse at dusk", "models": ["gpt-image-2", "flux-2-max"], "count": 2, "seed": 41}'{
"jobId": "<first job>",
"jobIds": ["<job 1>", "<job 2>", "<job 3>", "<job 4>"],
"batchId": "6b1f7e2a-0c4d-5e8f-9a1b-2c3d4e5f6a7b",
"groups": [
{ "model": "gpt-image-2", "jobIds": ["<job 1>", "<job 2>"], "credits": <credits> },
{ "model": "flux-2-max", "jobIds": ["<job 3>", "<job 4>"], "credits": <credits>,
"adjustments": [{ "field": "resolution", "from": "1K", "to": "2 MP", "reason": "..." }] }
],
"totalCredits": <credits>
}各画像には、その画像を 1 回の呼び出しで作った場合と同じ料金が請求されます。count と models を指定しない場合や count: 1 の場合、レスポンスは通常の { "jobId" } です。jobId は常に最初のジョブなので、それを読み取るコードはそのまま動作します。
- クレジットは、バッチ全体か、何も請求しないかのどちらかです。何かが作成される前に、残高がバッチの合計と照合されます。足りない場合、ルートは
requiredに合計を設定した402 insufficient_creditsを返し、何も作成されません。請求が途中で失敗した場合は、すでに作成されたジョブが、レスポンスの前に返還されて削除されます。 - べき等性は画像ごとです。
Idempotency-Key: Kを付けると、画像 i のキーはK:iになります。同じキーでリクエストを繰り返すと同じジョブ ID が返され、ジョブに二重に請求されることはありません。一部しか作成されなかったバッチは、残りが作成されます。同じキーで同時に送られた 2 回目のリクエストは、1 回目を待つか、15 秒後に409 batch_in_progressを返します。その場合は再試行してください。同じキーを異なるボディで、または別のルートで繰り返すと、422 idempotency_key_reusedが返されます。 - キューに入れられないバッチ。ジョブを開始のキューに入れられない場合、ジョブのクレジットは返還されてジョブは削除され、リクエストは
500 internal_errorを返します。同じキーで再試行すると、バッチがもう一度始まります。一部のジョブが開始していた場合、500はそれらをerror.startedJobIdsに示し、同じキーで再試行すると、それらが返って残りだけが開始されます。 - シード:
seedを指定すると、各モデルの画像 i にはseed + iが使われるので、画像はそれぞれ異なります。 - プリセットと組み合わせた場合、
countはプリセットのリクエストで N 枚の画像を作ります。modelsを指定すると、プリセットはモデルごとに 1 回ずつ適用されるので、各モデルにはそのモデル用のエディターのリクエストが送られます。 - 後からバッチを見つけられます。バッチのすべてのジョブは、同じ
input_data.batchIdと、input_data.batchIndexにその位置を持ちます。GET /v1/jobs?batchId=<id>で一覧表示できます。 - 何かが作成される前に
400 validation_errorで拒否されるもの:1〜4 の範囲外のcount、2 個未満または 4 個を超えるmodels、重複したモデルや不明なモデル、providerと一緒に指定したmodels、8 枚を超える画像です。デプロイメントが提供していないモデルには、403 model_not_availableが返されます。
マスクを生成する
POST /v1/generate-mask は、画像の中からテキストで説明した被写体を選び、白黒のマスク画像を返します。白い部分が被写体です。ボディは { imageUrl, prompt, threshold? } です。
promptは 1〜500 文字です。たとえば"the person"(人物)です。thresholdは 0〜1 で、デフォルトは 0.3 です。値を小さくすると、選ばれる範囲が広がります。
ボディの形式が正しくない場合は 400 validation_error です。応答は { jobId } です。完了したジョブの出力は { maskUrl, imageUrl } です。maskUrl はマスクの PNG で、imageUrl は元の画像がそのまま渡されたものです。どちらもインペイントの編集に渡してください。1 回の実行は 55 クレジットで、GET /v1/credits/model-cost?model=generate-mask も同じ料金を返します。マスク生成を参照してください。
画像をレイヤーに分割する
POST /v1/split-into-layers は、1 枚の画像をベース画像と個別のレイヤーに分けます。要素ごとに、それぞれ透明な PNG になります。ボディは { imageUrl, maxLayers?, size?, prompt?, sessionId?, origin? } です。
imageUrlは http(s) の URL です。maxLayersは 1〜99 で、デフォルトは 9 です。要素がこれより多い画像では、要素がまとめられてレイヤーが少なくなります。省かれる要素はありません。sizeは"1K"(デフォルト)、"1.5K"、"2K"、"auto"で、各画像のピクセル数の目安です。1K は約 100 万ピクセルで、"auto"は画像本来のサイズ(1K〜2K)を保ちます。promptは 2,000 文字までで、分離する対象を指定します。範囲を示す<bbox>x1 y1 x2 y2</bbox>(0〜1000)を含められます。空欄にすると、主な要素が自動で見つかります。sessionIdとoriginは、ジョブを作成するほかのルートと同じように働きます。省略可能なIdempotency-Keyヘッダーを付けると、同じキーでの再試行は、すでに開始したジョブについて{ jobId, deduped: true }を返します。
ボディの形式が正しくない場合は、クレジットが確保される前に 400 validation_error になります。応答は { jobId } です。完了したジョブの出力は { imageUrl, layers, layerData, layerCount, layersNotSaved, libraryImages } です。
imageUrlはベース画像(不透明な PNG)で、layersは各レイヤーのファイルを下から上の順に並べます。layerDataには、レイヤーごとに{ name?, description?, zIndex, width?, height?, box?, boxNormalized?, url, baseUrl }が同じ順で入ります。zIndexは重なり順で、1 がベースのすぐ上、数が大きいほど上に描かれます。box({ x1, y1, x2, y2 }、左上と右下)は、ベース上でのレイヤーの位置を、ベースのピクセルで示します。boxNormalizedは、同じボックスを 0〜1000 の尺度で示します。widthとheightは、レイヤーのファイル自体のピクセル数です。レイヤーは要素ごとに切り抜かれているため、元の位置に戻すにはboxに合わせて拡大縮小してください。
実行は、返す可能性のある最大の画像数(ベースを含めて maxLayers + 1)の料金を、そのサイズで確保します。請求されるのは、返した画像の分だけです。1K と 1.5K は同じ料金で、2K と auto も同じです。要素が見つからなかった実行はベースだけで完了し、画像 1 枚分の料金になります。保存できなかったレイヤーは省かれて layersNotSaved に数えられ、課金されません。POST /v1/quote で、実行前に確保額がわかります。実行の見積もりを参照してください。レイヤーに分割も参照してください。
動画を生成する
動画を作るルートは 2 つあります。POST /v1/generate-video は、画像からアニメーションを作ります。imageUrl の開始フレーム、任意で endFrameUrl の最後のフレーム、または、対応しているモデルではリファレンスだけです。POST /v1/text-to-video は、プロンプトだけからクリップを作るので、prompt が必須です。provider を省略すると、プラットフォームのデフォルトの動画モデルが使われます。
POST /v1/text-to-video は、任意の contentPolicyRewrite ブール値も受け取ります。指定しないか true の場合、著作権による拒否は、言い換えたプロンプトで 1 回だけ再試行され、ジョブの出力に contentPolicyRewrite: { original, rewritten } が含まれます。false の場合、著作権による拒否でジョブは失敗します。
{
"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 だけです。Seedance 2.5 は、1 回の呼び出しで最大 30 秒を作れます。開始フレームがある場合、常にそのフレームのアスペクト比でレンダリングします。 - Seedance 2.5 Flash(
seedance-2-5-flash)は、より速く、より安い Seedance 2.5 です。こちらも 1 回の呼び出しで最大 30 秒を、480pまたは720p(既定)で作ります。1080pのリクエストは 720p でレンダリングされ、720p で課金されます。リファレンスは画像 10 枚、動画 5 本、オーディオ 5 本までです。それを超えると、何かを確保する前に、上限を示した400 too_many_referencesが返されます。エディターやワークフローでの実行では、代わりに最初のものが送られます。リファレンスのオーディオは、1 本が 2〜30 秒で、合計 30 秒までです。WAV でも MP3 でもないクリップは、送る前に MP3 に変換されます。リファレンスのオーディオだけを付けたプロンプトも、有効なリクエストです。開始フレームとreferenceTaskTypeは、Seedance 2.5 と同じように働きます。draftはなく(無視されます)、seedも受け付けません。POST /v1/video-to-videoでは、seedance-2-5と並ぶ編集モデルです。 - MiniMax H3 の
resolutionは2Kまたは768Pで、まさにこの表記で指定します。送信する値は、GET /v1/nodes/:typeのproviderResolutionWireに一覧表示されます。 - Seedance 2 と MiniMax H3 では、フレームとリファレンスを組み合わせられます。開始または終了フレームと一緒にリファレンスを送信すると、そのフレームは固定の始点や終点ではなく、プロンプト内の番号付きリファレンスになります。Wan 3.0 では両方を送れないため、代わりにフレームがリファレンスの一覧の末尾に追加され、呼び出しはそのまま成功します。
- リファレンス動画は、料金が高くなります。課金対象にしているモデルでは、リファレンスクリップの料金は、そのクリップ自体の長さと出力の長さを合わせて決まります。そのため、元のクリップが長いほど、確保されるクレジットも増えます。Wan 3.0 は、出力の秒数だけを課金します。Kling 4.0 と Kling 4.0 Flash は、出力の秒数に、出力とクリップのうち長いほうの秒数を足して課金します。そのため、出力より短いクリップは、出力と同じ長さとして数えられます。
characterReferencesは実在の人物の顔を保ちます。対象は Gemini Omni と Gemini Omni Flash です。各エントリは{ imageUrl, description, bodyImageUrl?, name?, voice? }で、ポートレート、最大 2,000 文字の人物の説明、任意の全身の画像、最大 100 文字の任意の名前です。referenceImageUrlsはモデルにとって緩やかな文脈ですが、この入力は顔を保ちます。Gemini Omni Flash 1.2 は最大 2 人を受け付けます。ほかのモデルは400 character_references_unsupportedを返します。同じリクエストに開始フレームまたは終了フレームがあると、400 character_references_with_start_frameまたは400 character_references_with_end_frameが返されます。Gemini Omni のモデルは、人物とフレームを組み合わせないためです。Gemini Omni と Gemini Omni Flash では、リクエストは、モデルの入力予算である 7 単位に収まる必要があります。画像は 1 つにつき 1、動画は 2、人物は 1(bodyImageUrlがあれば 2)と数えます。予算を超えたリクエストには400 character_references_quotaが返されます。Gemini Omni Flash 1.2 では、人物はどの予算にも数えられず、voiceには400 character_voice_unsupportedが返されます。キャラクターリファレンスでクレジットは増えません。- Kling 4.0(
kling-4)は、テキストだけでも、リファレンス素材からでも実行でき、素材は全部で最大 15 個です。受け取るのは、referenceImageUrls(最大 10 個)、referenceVideoUrls(最大 5 個、それぞれ 2〜30 秒。6 個目には400 reference_videos_over_limitが返されます)、characterReferences(最大 7 個)、referenceAudioUrls(最大 3 個)です。これを超えると、何も確保される前に400が返されます。リクエストにcharacterReferencesがあればcharacter_references_quota、なければvalidation_errorです。imageUrlやendFrameUrlは画像として数えられます。あなた自身のリファレンス画像の後に加わり、プロンプトでは最初または最後のフレームとして示されます。各キャラクターリファレンスは名前付きの被写体です。imageUrl、bodyImageUrl、最大 3 個のextraImageUrlsがその 2〜4 枚の画像で、プロンプトでは@<name>と呼ばれます。画像が 1 枚だけのエントリは、通常のリファレンス画像として送られます。開始フレームや終了フレームと一緒に使えます。voiceには400 character_voice_unsupportedが返されるので、声のクリップはreferenceAudioUrlsで送ってください。プロンプトでは、素材を@image_N、@video_N、@<name>、@audio_Nで指定します。リクエストにない素材への言及は@が取り除かれるので、実行はそのまま始まります。リファレンス動画を使う実行は、出力の秒数に、出力とリファレンス動画のうち長いほうの秒数を足した分が、リファレンス料金で 1 秒ごとに課金されます。 - Kling 4.0 のオーディオサウンドトラック(デフォルトでオン)。最初の
referenceAudioUrlsのクリップが、結果のサウンドトラックとして再生されます。このクリップは、もう 1 本のリファレンス動画として送られます。オーディオを載せた静止フレームで、長さはオーディオと同じ、2 秒以上、出力以下です。その音声は残されるので、人物は正確にそのトラックに合わせて演技します。それ以降のクリップは名前付きの声のままで、@audio_2は@Voice1になります。サウンドトラックは、5 個あるリファレンス動画の枠を 1 つ使い、実行はリファレンス動画を使う実行として課金されます。audioSoundtrack: falseにすると、すべてのクリップがボイスのサンプルのままになります。サウンドトラックがある場合、Kling は送信したリファレンス動画の音声も残します。 - Kling 4.0 Keyframes(
kling-4-keyframes)は、開始フレームのimageUrl、順番どおりの最大 8 個の中間フレームのreferenceImageUrls、endFrameUrlを受け取ります。終了フレームだけでも使え、フレームがまったくなければテキストから動画を作ります。フレームの総数の上限はdurationで決まります。3 秒で 4 個、1 秒ごとに 1 個増え、9 秒以上で 10 個です。それを超えるか、中間フレームが 8 個を超えると、何も確保される前に400 validation_errorが返されます。プロンプトでは、フレームは@first_frame、@keyframe_N、@last_frameで、@image_Nは@keyframe_Nに書き換えられます。aspectRatioは、フレームがない場合にだけ適用されます。リファレンス動画、オーディオ、キャラクターは受け取りません。 - どちらの Kling 4.0 モデルも、
durationは 3〜30 の整数秒(デフォルトは 5)、resolutionは720p(デフォルト)または1080pです。ほかの解像度は 720p でレンダリングされ、課金されます。aspectRatioはauto(デフォルト。素材に合わせ、素材がなければ 16:9)、16:9、9:16、1:1、21:9のいずれかです。音声は常にオンで(soundは無視されます)、seedはありません。プロンプトは最大 8,000 文字です。料金は秒単位で、無料プランでは使えません。 - Kling 4.0 Flash(
kling-4-flash)は、送った内容からモードを選びます。referenceImageUrls、referenceVideoUrls、characterReferencesのないimageUrlは、正確な開始フレームになります。そのときaspectRatioは使われず、プロンプトではそのフレームを@first_frameと呼びます。それ以外はリファレンスモードで実行されます。プロンプトだけ、リファレンス、キャラクター、またはそれらと一緒の開始フレームです。リファレンスモードでは、kling-4と同じく、imageUrlはあなた自身のリファレンス画像の後に加わります。 - Kling 4.0 Flash のリファレンス。リファレンスモードでは、
referenceImageUrls(最大 10 個)、referenceVideoUrls(最大 5 個、合計 2〜20 秒)、characterReferences(kling-4と同じく、名前付きの被写体を最大 7 個)を受け取り、素材は全部で最大 15 個です。リファレンス動画の合計が 2〜20 秒の範囲外の場合、または 6 個目の動画がある場合は、何も確保される前に400が返されます。別個の声はありません。referenceAudioUrlsの N 番目のクリップ(最大 7 個)が、順番どおりcharacterReferencesの N 番目のエントリの声になります。声を持たせるには、キャラクターに 2〜4 枚の画像、またはvideoUrlが必要です。画像が 1 枚だけで動画もないキャラクターのクリップと、最後のキャラクターより後のクリップは取り除かれ、実行はそのまま始まります。クリップは素材の枠を使わず、@audio_Nの言及は@が取り除かれます。keepOriginalSoundはkling-4と同じように働きます。audioSoundtrackはありません。 - Kling 4.0 Flash の設定。
durationは 3〜20 秒(デフォルトは 5)です。このモデルは 720p だけでレンダリングするため、どのresolutionを指定しても 720p でレンダリングされ、課金されます。aspectRatioはkling-4と同じで、音声は常にオン、seedはなく、プロンプトは最大 8,000 文字です。終了フレームはありません。imageUrlやリファレンスと一緒のendFrameUrlは、モデルに送られません。POST /v1/generate-videoでendFrameUrlだけを送ると、400(imageUrl is required)が返されます。料金は 1 秒ごとで、両方のモードで同じ単価です。リファレンス動画を使う実行は、出力の秒数に、出力とリファレンス動画のうち長いほうの秒数を足した分が、リファレンス料金で課金されます。ほかの Kling モデルと違い、無料クレジットでも 3 秒または 4 秒のクリップとして実行できます。 - PixVerse V6 Max(
pixverse-v6-max)は、1 つの ID で 2 つのモードを持ちます。POST /v1/generate-videoでは、imageUrlが正確な最初のフレームになり、クリップはその形になります。POST /v1/text-to-videoでは、aspectRatioは16:9(デフォルト)、4:3、1:1、3:4、9:16、2:3、3:2、21:9です。ほかの比率は、最も近い比率に移ります。durationは 1〜15 秒(デフォルトは 5)です。resolutionは360p、540p、720p(デフォルト)、1080pで、ほかの値は 720p でレンダリングされ、課金されます。seedは 0〜2147483647 の整数で、プロンプトは 5,000 文字までです。 - PixVerse V6 Max の音声。
sound: falseでない限り、ネイティブ音声はオンです。soundがない場合は、generateAudio: falseでもオフになり、両方を送るとsoundが優先されます。音声は料金を変えます。長さと解像度ごとに、無音の料金と音声付きの料金があります。終了フレームはなく、リファレンスの画像、動画、音声もありません。これらはモデルに送られません。360p で 1〜4 秒なら、無料クレジットで実行できます。 - Grok Imagine 1.5(
grok-imagine-video-1.5)にはimageUrlが必要で、これが正確な最初のフレームになります。endFrameUrlは正確な最後のフレームで、両方に同じ URL を使うと継ぎ目のないループになります。中間フレームは最大 4 枚まで、順番にreferenceImageUrlsに入れます。中間フレームはクリップ全体に均等に、秒単位で配置されます。たとえば 8 秒のクリップに 2 枚なら、3 秒と 5 秒に置かれます。 - Grok Imagine 1.5 の上限。D 秒のクリップが受け付ける中間フレームは最大 D − 1 枚で、超えた分は拒否されずに省かれます。
imageUrlなしの中間フレームやendFrameUrlは、400 image_requiredになります。durationは 1〜15 秒(デフォルトは 8)です。resolutionは480p(デフォルト)、720p、1080pで、ほかの値は 480p でレンダリングされ、課金されます。seedはなく、リファレンスの動画、音声、キャラクターもありません。料金は解像度ごとの秒単位で、フレームによる追加料金はありません。 - 1080p の Grok Imagine 1.5 は、開始フレームだけを受け付けます。1080p の実行で、終了フレーム、ループ、中間フレームも送ると、クレジットが確保される前に
400 start_frame_only_resolutionになります。720p を選ぶか、ほかのフレームを外してください。480p と 720p では、すべてのフレームを使えます。 - Kling 4.0 と Kling 4.0 Flash の動画の被写体。
characterReferencesのエントリーに任意のvideoUrl(キャラクターを映した 3〜8 秒のワンショットのクリップ)を指定すると、そのエントリーは画像ではなくその動画から作られた被写体になります。imageUrlとdescriptionは引き続き必須です。クリップは実行のリファレンス動画に加わるため、リファレンス動画として計測され、上限も同じように適用されます。1 回のリクエストで使えるのは、このようなエントリー最大 3 個と、referenceVideoUrlsを含めた動画最大 5 本です。すべての動画の合計は、Kling 4.0 では 30 秒以内、Flash では 20 秒以内でなければなりません。また、2 つのエントリーで 1 つのクリップを共有することはできません。料金は画像だけのエントリーと同じなので、追加料金はかかりません。範囲外のリクエストには、何も確保される前に400が返されます:character_videos_over_limit、reference_videos_over_limit、character_video_shared、またはクリップが 3〜8 秒の範囲外の場合はvideo_too_longです。読み取れないクリップには400 character_video_unreadableが返されます。ほかのモデルには400 character_video_unsupportedが返されます。動画の被写体を参照してください。 voiceは、キャラクターリファレンスに 1 つの声を固定します。クリップをまたいで使われ、形は{ preset, description?, exampleLine? }です。presetは Gemini の声の ID のいずれかです。1 回のリクエストで固定できる異なる声は最大 3 つで、超えると400 character_voices_over_limitが返されます。声については動画生成を参照してください。
各モデルの長さ、解像度、クレジット料金については、動画モデルを読むか、GET /v1/models を呼び出してください。
Seedance 2.5 のリファレンスのタスクタイプ
POST /v1/generate-video と POST /v1/text-to-video は、省略可能な referenceTaskType を受け付けます。これは、リファレンスメディア(referenceImageUrls、referenceVideoUrls、referenceAudioUrls)の用途を Seedance 2.5 に伝えます。プロンプトからモデルに推測させる代わりです。
| 値 | 動作 |
|---|---|
auto | デフォルトで、フィールドがない場合も同じです。何も宣言せず、モデルがプロンプトから判断します。 |
reference | メディアは新しいクリップの手がかりになるだけです。リクエストは、送られたアスペクト比と長さのままです。 |
edit | クリップは、リファレンス動画の編集になります。動画自身の形と長さで作られ、aspectRatio は adaptive、duration は自動(-1)になります。リファレンス動画が 1 本以上必要で、プラットフォームが測定したすべてのリファレンス動画の長さが 4〜30 秒である必要があります。そうでない場合は何も宣言されず、リクエストは元の比率と長さのままです。 |
extend | クリップは、リファレンス動画の続きになります。動画自身の形で作られます(aspectRatio は adaptive)。自動の duration や duration がない場合は、モデルのデフォルトの長さ(GET /v1/models の defaultDuration)になります。返されるのは続きの部分だけで、元のクリップとはつながりません。両方を 1 本の動画にするには、動画を延長を使ってください。リファレンス動画が 1 本以上必要です。 |
-
ほかのモデルと、リファレンスメディアのないリクエストでは無視され、エラーにはなりません。開始フレームや終了フレームは、リファレンスメディアではありません。上の 4 つ以外の値は
400 validation_errorになります。このフィールドを受け付けるモデルは、GET /v1/modelsのreferenceTaskTypesに値を示します。 -
変更した内容は報告されます。
editやextendが置き換えた比率や長さはadjustmentsで返され、/v1/generate-videoではwarningsにも入ります。自動の比率は置き換えられません。リファレンス動画があれば、すでにadaptiveで実行されるためです。 -
料金は、実行時の値に従います。実行は、その値で料金が計算され、確保され、送られます。同じボディの
POST /v1/quoteも、同じ方法で料金を計算します。長さが自動のreferenceの実行は、モデルが作れる最長の出力で確保され、作った分が課金されます。 -
ドラフトも宣言します。
draft: trueのリクエストは、draftなしの同じリクエストとまったく同じようにタイプを宣言し、480p で作られます。editのドラフトを 1080p で仕上げると、同じ編集が元のクリップの長さで再レンダリングされます。 -
宣言されなかったことは報告されません。タイプを指定したのに宣言されなかったリクエスト(たとえばリファレンス動画がない場合)は、ほかのリクエストと同じように応答します。ジョブの
input_data.referenceTaskTypeは、タイプが宣言された場合にだけ設定されます。 -
POST /v1/video-to-videoでprovider: "seedance-2-5"を使うと、ボディの内容にかかわらず、常にeditを求めます。元のvideoUrlとreferenceVideoUrlsのすべてのクリップが 4〜30 秒の場合に、編集が宣言されます。そうでない場合は宣言なしで送られ、モデルがプロンプトを読みます。 -
ワークフローのノードに保存された値は、モデルが受け付ける場合にだけ残ります。ワークフローのグラフを保存するすべての書き込みで、動画生成、画像から動画、テキストから動画、動画から動画のノードの
referenceTaskTypeが確認されます。値が残るのは、ノードで実行するモデルがその値を挙げている間だけです。それ以外の場合はキーが削除され、ノードのほかの部分は変わりません。autoも削除されます。これは、POST /v1/workflows、PATCH /v1/workflows/:id、POST /v1/workflows/import、エディターでの保存、アプリやテンプレートの公開スナップショットに適用されます。MCP の書き込みと Copilot の編集では、削除が報告されます。
MCP では、このフィールドは generate_video の reference_task_type です。
リファレンスを使う
リファレンスは、モデルに合わせてほしい画像、そして動画ではクリップとオーディオでもあります。フラットな URL のリストとして送ることも、ルートが番号を振り、ラベルを付けてプロンプトに書き込む構造化されたリファレンスとして送ることもできます。これは、エディターが接続されたノードに対して行うのと同じです。
構造化されたリファレンス
connectedReferences は、POST /v1/generate-image、POST /v1/generate-video、POST /v1/text-to-video、POST /v1/extend-video で受け付けられます。各エントリーは、1 枚の画像を表します。
プロパティ
型
動画のルートでは、これらのエントリーを番号付きのリファレンスに変換します。
- メンションしなかったリファレンスは、すべて添付されます。その URL は重複を除いてリファレンスの一覧に加わり、
@image_1 (reference): <label>のような行が付きます。wired-characterのエントリーは、代わりに「Use these characters:」(これらのキャラクターを使う)という指示の一部になります。 - 一覧は、番号を振る前に、そのモデルの上限で打ち切られます。そのため、プロンプト内のリファレンス番号が、送信されていない画像を指すことはありません。
- プロンプト内の
{image:N:label}は、添付されたリファレンスに対して番号が振られ、「@image_Nからの label」になります。 {ref:<id>}と{ref:<id>:label}は、指定したidでリファレンスを指定します。プラットフォームは、一覧に番号を振った後に、そのトークンをリファレンスの番号に置き換えます。そのため、番号は自分で計算する必要がありません。一覧には、まずフラットなreferenceImageUrls、次にメンションしなかったキャラクター、その後は指定した順のほかのエントリー、という順序で番号が振られます。上限を超えていた、あるいはモデルがリファレンスを受け付けないなどの理由でリファレンスが添付されなかったトークンは、そのラベルに、それもなければdefaultNameに、それもなければ何もない状態にフォールバックします。生のテキストのままモデルに渡ることはありません。referenceOrderは、リファレンス ID のリストで、リファレンスの順序を変え、それに合わせて番号も振り直します。POST /v1/generate-imageでも使えます。
表示用のコピーは、元のファイルに置き換えられます。これは、POST /v1/generate-video と POST /v1/text-to-video のすべての画像入力に当てはまります。imageUrl、endFrameUrl、referenceImageUrls、接続されたリファレンスやキャラクターのリファレンスです。Nodaro の CDN の画像をリサイズした表示用のコピー、https://cdn.nodaro.ai/cdn-cgi/image/<options>/<path> の入力は、元のファイル https://cdn.nodaro.ai/<path> として記録され、送信されます。トレンドの実行と Video Remake の実行の画像にも、同じことが当てはまります。ほかのホストの URL は、送信したとおりに使われます。
モデルに渡す前に、埋め込まれたメタデータが取り除かれます。入力画像の中には、Content Credentials、EXIF、XMP、IPTC、PNG のテキストチャンクなど、埋め込まれたデータを持つものがあります。そうした画像は、モデルに送る前に、元の形式のまま、そのデータを除いて再エンコードされます。そうしたデータがない画像は、そのまま送られます。保存されているファイルは変わりません。
connectedReferences が扱うのは画像だけです。referenceVideoUrls と referenceAudioUrls は、フラットなリストのままです。connectedReferences を省略すると、ルートは以前と同じように動作します。prompt と referenceImageUrls は、そのまま送信されます。
POST /v1/generate-image と MCP ツール generate_image では、prompt 内の {image:N} または {image:N:label} トークンは、N 番目のリファレンス画像を指します。
- 接続されたリファレンスがない場合、N はフラットな
referenceImageUrlsを順に数えます。つまり{image:1}は、送信した最初の URL です。ほかのリファレンスがdescribedReferencesだけのリクエストも、これに含まれます。 connectedReferencesのエントリーが 1 つ以上ある場合、N はconnectedReferencesのエントリーを順に数えます。同じリクエストのフラットなreferenceImageUrlsも、接続されたリファレンスより前に添付されますが、それを指すトークンはありません。プロンプトで写真を指定するには、その写真をconnectedReferencesのエントリーとして送信してください。- その位置に画像がないトークンは、そのラベルになります。
{image:2:person}はpersonと読まれます。ラベルのない{image:2}は省かれます。
独自の画像上限を持つモデルは、余分な画像を拒否します。Seedream 5.5 と FLUX 3 Klein が受け付ける入力画像は最大 10 枚です。GPT Image 2.6 Flare、GPT Image 2.6 Sunburst、MiniMax H3 Image は最大 16 枚です。ベース画像も上限に数えられます。それより多く送ろうとするリクエストは、何も請求される前に 400 validation_error で拒否され、メッセージには何枚減らせばよいかが示されます。フラットな referenceImageUrls、connectedReferences、ベース画像がすべて数えられます。これらのモデルでは、connectedReferences と referenceOrder は、referenceImageUrls と同じく最大 16 件のエントリーを受け付けます。判断の基準になるのは、リクエストが送る画像の枚数で、同じ画像を共有するエントリーは 1 枚として数えられます。たとえば、10 枚の異なる画像を 15 回指定するリクエストは、Seedream 5.5 で実行されます。それ以外のすべてのモデルでは、connectedReferences と referenceOrder の上限は 14 件のままです。モデルを指定しないリクエストには、実行されるモデル、つまりアスペクト比のデフォルトの上限が適用されます。POST /v1/image-to-image も同じように応答し、imageUrl も数えられます。Seedream 5.5、GPT Image 2.6、MiniMax H3 Image で実行するワークフローでは、最初の 10 枚または 16 枚が送られ、残りは省かれます。FLUX 3 Klein は、ワークフローでも拒否します。
エディターとワークフローの実行でも、トークンには同じように番号が振られます。テキストノードなど、間にあるノードを経由して画像生成ノードに届いた画像も、送信され、番号が振られます。
画像のリファレンスに対応する動画モデル
| モデルファミリー | 画像のリファレンス |
|---|---|
| Seedance 2 系列 | 最大 9 |
| HappyHorse Ref2V | 最大 9 |
| Gemini Omni、Kling 3 Omni、Grok Imagine (I2V) | 最大 7 |
| VEO 3.1 Fast、VEO 3.1 Lite | 最大 3 |
それ以外のモデルでは、{image:N} トークンはラベルに置き換えられるだけで、何も添付されません。VEO 3.1 Quality は一覧にありません。veo3 で送ったリファレンスは無視され、実行にはそのフレームが使われます。
リファレンスだけから動画を作る
POST /v1/generate-video では、送信するリファレンスの種類のうち少なくとも 1 つにモデルが対応していれば、開始フレームは省略できます。たとえば、referenceImageUrls だけを使う Kling 3 Omni です。VEO 3.1 Fast または Lite でリファレンスだけの実行を行うと、自動でリファレンスモードに切り替わるため、generationType は不要です。モデルが使えない種類のリファレンスは数に入りません。画像だけを受け付けるモデルにオーディオだけのリファレンスを送ると、400 で拒否されます。
終了フレームだけも、それをリファレンスに組み込むモデルでは使えます。Seedance 2 系列、MiniMax H3、Wan 3.0 です。endFrameUrl を 1 回送信するだけでよく、referenceImageUrls に同じ画像を重ねて指定する必要はありません。@nodaro/shared パッケージは videoProviderFoldsLoneEndFrame(provider) をエクスポートしているので、自分のインターフェースでも同じ規則を使えます。
リクエストに開始フレームもリファレンスモードもなく、モデルが使えるリファレンスもない場合、応答はモデルによって異なります。
- Kling 3 Omni、HappyHorse Ref2V、Hailuo 2.3 のように、テキストだけから動画を作れないモデルは、
400 image_requiredを返します。メッセージには、代わりにリファレンスが使えるかどうかが示されます。該当するモデルについては、GET /v1/modelsが正式な情報源です。 - それ以外のすべてのモデルは
400 validation_errorを返し、プロンプトだけのクリップにはPOST /v1/text-to-videoを使うように伝えます。
一部のモデルには、テキストから動画用と画像から動画用の 2 つの ID があります。Grok Imagine(grok と grok-i2v)、Wan(wan と wan-i2v)、Wan 2.7(wan-2.7-t2v と wan-2.7-i2v)、HappyHorse(happyhorse と happyhorse-i2v)です。POST /v1/generate-video は画像から動画のルートです。ここでテキストから動画用の ID を imageUrl やリファレンス画像と一緒に指定すると、画像から動画用の ID として実行されます。料金、ジョブの記録、送信はその ID で行われ、POST /v1/quote も同じように見積もります。どちらかの ID を指定したプロンプトだけのリクエストには、上記の 400 validation_error が返されます。POST /v1/text-to-video では、テキストから動画用の ID を指定してください。そこで画像から動画用の ID を指定すると 400 validation_error になります。どちらの拒否も、何かが確保される前に行われます。
動画を延長
POST /v1/extend-video が connectedReferences と referenceImageUrls を受け付けるのは、provider: "seedance-2-5-extend"(Seedance 2.5)、"seedance-2-5-flash-extend"(Seedance 2.5 Flash)、"seedance-2-0-extend"(Seedance 2.0)のときだけです。seedance-2-extend を指定した古いリクエストは、Seedance 2.5 として実行されます。それ以外の延長用モデルは、リファレンスを 400 で拒否します。上限は、どのモデルも自分の画像 8 枚です。元のクリップの最後のフレームが、リファレンス枠を 1 つ使うためです。この枠は自分の画像の後に置かれるので、自分の番号がずれることはありません。元のクリップの終わりは @video_1 として渡されます。Seedance 2.5 では最後の 10 秒、Seedance 2.0 では最後の 2 秒です。Seedance 2.5 と Seedance 2.5 Flash は最後のフレームのアンカーを送らず、画像 8 枚の上限も同じです。Seedance 2.5 Flash では、2 秒より短い元のクリップは延長できません。リファレンス画像によって、クレジットが追加でかかることはありません。動画を延長には direction も subject もありません。プロンプトは、すでに見た目が決まっているクリップの続きだからです。
説明だけのリファレンス
describedReferences は、説明はできるが、まだ画像がない被写体を指定します。台本の役どころなどです。POST /v1/generate-image、/v1/generate-video、/v1/text-to-video、/v1/extend-video は、{ name, description } のエントリーを最大 10 個受け付けます。name は最大 80 文字、description は最大 2,000 文字です。
- 何も添付されません。説明だけのリファレンスはリファレンス枠を使わないため、ほかのリファレンスの番号も変わりません。
- モデルには、1 行のテキストとして渡されます。
<Name> — <description>.という形です。プロンプトには名前をそのまま残します。たとえばNatalie walks down the pier.(Natalie が桟橋を歩いていく。)のようにします。この行が、Natalie が誰であるかをモデルに伝えます。@によるメンションは書かないでください。その記法は、添付された画像を指すためのものです。 - 単独でも機能します。
connectedReferencesなしでdescribedReferencesだけを送信できます。まだキャラクターが存在しない段階で書かれたストーリーでは、これが一般的なケースです。 - 名前か説明のないエントリーは取り除かれ、同じ名前が繰り返されている場合は 1 回だけ書き込まれます。説明だけのリファレンスは URL を持たないため、どの延長用モデルでも使えます。
実行ごとの説明とキャプション
descriptionOverrideは、connectedReferencesのエントリーに指定するもので、このリファレンスがこの実行に限って何であるかを、最大 2,000 文字で示します。保存された説明より優先して、リファレンスの指示にすでにある説明を埋めます。指示に説明がない場合は、1 行を追加します。そのため、モデルに伝わるのは 1 回だけで、2 回になることはありません。referenceVideoCaptionsとreferenceAudioCaptionsは、POST /v1/generate-videoと/v1/text-to-videoで、リファレンスのクリップとオーディオを、それぞれ最大 500 文字で説明します。これらはインデックスで対応しています。referenceVideoCaptions[0]はreferenceVideoUrls[0]を説明します。それぞれが@video_1: <caption>.のような行になり、空のエントリーは、対応をずらさずに 1 つのクリップを読み飛ばします。
プロンプトでリファレンスをメンションする
POST /v1/generate-image では、リファレンスを末尾の一覧に残す代わりに、文の中に置くことができます。@<name-slug>:<index> と書くか、@<name-slug>:<index>:<role> と書いて、そこから何を取り入れるかを指定します。
{
"prompt": "a wide shot of @nessie:1 rising beside @dock:2:material",
"connectedReferences": [
{ "id": "cr-1", "defaultName": "Nessie", "source": "wired-creature", "url": "https://…/nessie.png" },
{ "id": "ob-1", "defaultName": "Dock", "source": "wired-object", "url": "https://…/dock.png" }
]
}モデルは「a wide shot of the creature from reference image A rising beside the material from reference image B」(画像 A のクリーチャーが画像 B の素材の横に現れるワイドショット)を受け取ります。
- スラッグは
defaultNameから作られます。小文字にし、それ以外の文字の連続は 1 つの-に変換します。Old Townはold-townになります。スラッグを設定するフィールドはありません。 - インデックスは、メンションをリファレンスに一致させるためだけのものです。プロンプトに書き込まれることはなく、リファレンスへの番号付けはプラットフォームが自分で行います。
- 画像(
manualとwired-image)の役割は、object、person、face、clothes、background、style、pose、textureです。クリーチャーはcreature、anatomy、markings、pose、color、styleを取ります。オブジェクトはobject、shape、material、color、texture、styleを取ります。それ以外の 1 語は、書かれたとおりに渡されます。役割を指定しない場合は、そのエントリーのdefaultRoleが適用されます。 - メンションの後に付ける
~lockと~nolockは、@town:1:background~lockのように、そのメンションに限って、リファレンスの顔の固定をオンまたはオフにします。 - 名前は、次の順序で照合されます。キャラクター、ロケーション、画像、クリーチャー、オブジェクトです。キャラクターと画像が同じ名前を共有している場合はキャラクターを意味し、同じ種類の中では、最初に一致したものが優先されます。
- スラッグが数字で始まる名前は、メンションできません。たとえば
3D Renderは3d-renderになります。メンションするには、リファレンスの名前を変更してください。モデルの上限を超えていたリファレンスへのメンションは、そのままの文字として残ります。 - リファレンスをメンションすると、その位置が移動します。末尾の一覧から、入力した場所へと移ります。それより後のリファレンスの文字も、文に合わせて変わります。クリーチャーやオブジェクトでは、メンションによって、末尾に追加されるはずだった行も置き換えられます。
リファレンスの固定
POST /v1/generate-image の referenceLock は、シーンの前に、検証済みの、リファレンスに忠実に従わせる Nodaro の言い回しを追加します。
| 値 | 追加される内容 | 使う場面 |
|---|---|---|
standard | リファレンスに写っているものだけを使い、似姿を保ち、それらを組み合わせるという指示 | 複数のリファレンスからの合成 |
multi-person | 上記に加えて、顔を変えたり混ぜたりしないという規則 | 1 つのショットに 2 人以上の顔 |
送信するのはテキストではなく ID です。言い回しはプラットフォーム側が持っており、クライアントを更新しなくても改善されます。フィールドを省略すると、ロックは追加されません。
ID による演出
direction は、カメラ、光、ルックを、文章ではなくピッカー ID で表します。POST /v1/generate-image、POST /v1/generate-video、POST /v1/text-to-video が受け付けます。Nodaro は、各 ID に対応する検証済みの言い回しを、自分でプロンプトに書き込みます。そのため、保存したリクエストは、クライアントが書いたテキストのまま固定されるのではなく、時間とともに改善された言い回しを取り込みます。
{
"prompt": "a knight on a hill",
"provider": "nano-banana-pro",
"direction": {
"shotSize": "wide-shot",
"lens": "wide-24mm",
"lightingStyle": "rembrandt",
"style": "anime",
"mood": ["happy", "joyful"]
}
}キーと、その ID の取得元
各キーは、クリエイティブコントロールピッカーの 1 つのフィールドです。有効な ID は、エディターのピッカーが使うのと同じカタログである GET /v1/picker-catalogs/<picker> から取得します。
| キー | ピッカー | 画像 | 動画 |
|---|---|---|---|
shotSize、angle、coverage、composition、vantage | フレーミング | はい | はい |
pose | ポーズ | はい | はい |
compositionEffect | 構図エフェクト | はい | はい |
cameraFormat | カメラ/フィルム | はい | はい |
lens | レンズ | はい | はい |
aperture、shutterSpeed、isoValue | 露出設定 | はい | いいえ |
timeOfDay、lightingStyle、lightingDirection、lightingRatio、colorTemperature | ライティング | はい | はい |
colorLook | カラー/ルック | はい | はい |
atmosphere | 大気効果 | はい | はい |
postProcess | ポストプロセスエフェクト | はい | いいえ |
style | スタイル | はい | はい |
mood | ムード | はい | はい |
aesthetic | テイスト | はい | はい |
photoGenre | 写真ジャンル | はい | いいえ |
photographer | 写真家 | はい | いいえ |
renderQuality | レンダリング品質 | はい | いいえ |
setting | 舞台設定 | はい | はい |
era | 年代/時代 | はい | はい |
backdrop | 背景 | はい | はい |
cameraMotion | カメラモーション | いいえ | はい |
actionFx | アクション FX | いいえ | はい |
temporalSpeed、temporalFreeze、temporalDirection、temporalShutter | 時間表現 | いいえ | はい |
transition | トランジション | いいえ | はい |
loopSubject | ループの被写体 | いいえ | はい |
あるルートに当てはまらないキーも受け付けられ、何も追加しないだけです。そのため、ルックの ID を 1 つのマップにまとめて、変更せずに画像と動画の両方のルートに送信できます。
値と上限
- 1 つの ID か、リストです。複数選択のキーである
mood、aesthetic、photographer、atmosphere、postProcess、composition、lightingStyleは、それぞれ独自の上限まで受け付け、それを超える ID は取り除かれます。単一選択のキーにリストを指定した場合は、最初のエントリーが使われます。 - 拒否される上限が 2 つあります。
400 validation_errorになるのは、1 つのキーに 8 個を超えるエントリーを指定した場合と、100 文字を超える ID を指定した場合です。 - なしと空は違います。キーがないことは、ヒントがないことを意味し、デフォルト値を意味することはありません。空の文字列や空のリストも、何も追加しません。
- 自分のパレットとムードボードが読み飛ばされることはありません。
/v1/generate-imageでは、colorLookは"palette:<id>"も、styleは"moodboard:<id>"も受け付けます。自分のパレットとムードボードを参照してください。 - 不明なキーと不明な ID は、拒否されずに読み飛ばされます。古いサーバーに新しいクライアントを使うと、エラーの代わりにヒントが減るだけです。新しいキーを送るクライアントより先に、サーバーを更新してください。
- カスタムのカタログパックです。独自のカタログパックを登録したデプロイ環境では、
GET /v1/picker-catalogsが、パックが追加する ID を一覧表示します。これらの ID は受け付けられますが、directionに言い回しを追加することはありません。
言葉が入る場所
これらの一節は、プロンプトの後の [style] セクションに追加されます。フィルムの行には cameraFormat、colorLook、style、era が、シーンの行にはそれ以外のルックのキーが入ります。
a knight on a hill
[style]:
<film line>
<scene line>- 行の中の順序は、プラットフォーム側の固定の順序であり、指定したキーの順序ではありません。2 つのキーが同じ一節を指すと、それは 1 回だけ書き込まれます。
- 何も入らない行は省かれます。どのキーも何も追加しない場合、セクション自体がなくなり、
promptはそのままモデルに渡ります。 - 動画のルートでは、モーションのキーは異なる働き方をします。
cross-dissolveのような短い専門用語を追加し、本文の中、つまり自分の文章の後にとどまります。モーションはショットの一部だからです。cameraMotionが最初に来ます。[style]セクションに入るのは、ルックのキーだけです。 - 動画のルートでは、
styleは、スタイルの画像向けの文言ではなく動画向けの文言を、同じ[style]セクションに追加します。動画向けの文言は動きのあるショットのために書かれています。まず媒体を示し、次にその技法を示します。写真系のスタイルは実写の媒体を示すので、写真のままになります。そのため、同じ"style": "anime"でも、動画のルートと generate-image では読まれ方が異なります。jobs.input_data.promptには、モデルが受け取ったテキストが記録されます。カタログのエンドポイントが返すのは、画像向けの文言だけです。キャンバスでも同じように動作します。画像向けと動画向けのスタイルを参照してください。
プロンプトが長すぎる場合
各モデルが受け付けるプロンプトの長さには、それぞれ上限があります。direction をすべて含めると、それだけで小さな上限を超えることがあります。たとえば、画像側の Seedream では 3,000 文字、動画側の Kling では 1,000 文字です。そうなった場合、Nodaro は、固定の順序の末尾から、プロンプトが収まるまで、direction の一節を 1 つずつ取り除きます。それより先に、ほかの部分が取り除かれることはありません。
- subject の一節が取り除かれるのは、direction の一節がすべて取り除かれた後だけです。
- 自分の文章、リファレンス、それらを結び付ける語句、
@によるメンション、Style:とAvoid:の行は、常に残ります。 - ヒントがなくなってもまだプロンプトが収まらない場合に限り、テキストの末尾が切り詰められ、
...が追加されます。
動画のルートでは、この予算に、ルートが追加するリファレンスの指示も数えられ、これらが取り除かれることはありません。ネガティブプロンプトの設定がないモデルでは、negativePrompt が Avoid: の行として追加され、その分の余地が最初に確保されます。そのため、長いネガティブプロンプトは、文章ではなくヒントの一節を犠牲にします。任意の injectCharacterContext のテキストは、この処理の後に追加され、この予算には含まれません。
ジョブには、何が起きたかが記録されます。input_data.prompt はモデルが受け取った内容、input_data.userPrompt は自分が送信したテキスト(direction だけを送信した場合は空の文字列)、input_data.direction は送信したとおりの ID です。
ノードに保存された演出
保存されたワークフロー内の画像生成ノードは、API、MCP、またはワークフローを作成するアプリが書き込んだ、同じ direction オブジェクトをデータの中に持てます。エディターは、実行のたびに、そして最終的なプロンプトのプレビューでも、これを反映します。保存された ID は、接続されたフレーミング、ライティング、スタイルのピッカーに追加されます。接続によるヒントが先に来て、その後に保存された ID が続きます。プリセットとワークフローのエクスポートは、ノードのほかの部分と一緒に ID を保持します。
自分のパレットとムードボード
パレットは自分で決めた 2〜12 色のセットで、ムードボードは自分で決めた 1〜12 枚のリファレンス画像と説明のセットです。一度保存すれば、組み込みのカラールックやスタイルを選ぶのと同じ方法で、どの POST /v1/generate-image の実行もそれで方向づけられます。すべてのエディションで使えます。エディターでの働きについては、パレットとムードボードを参照してください。
| パレット | ムードボード | |
|---|---|---|
| 中身 | 1〜80 文字の名前、#RRGGBB 形式の 2〜12 色、最大 500 文字の任意のメモ | 名前、最大 1,000 文字の任意の説明、1〜12 枚の画像 { url, caption? } |
| 使い方 | direction.colorLook: "palette:<id>" | direction.style: "moodboard:<id>" |
| 実行に渡るもの | すべての色が、日常的な色名と 16 進コードでプロンプトに入ります | 説明がプロンプトに入り、画像がスタイルリファレンスとして送られます |
{
"prompt": "a lighthouse on a cliff at dusk",
"provider": "nano-banana-pro",
"referenceImageUrls": ["https://example.com/my-lighthouse.png"],
"direction": {
"colorLook": "palette:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f",
"style": "moodboard:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"lightingStyle": "rembrandt"
}
}パレットとムードボードを管理する
| メソッド | パス | ボディまたはクエリ | 内容 |
|---|---|---|---|
GET | /v1/palettes | limit(1〜100、デフォルトは 50)、cursor | 自分のパレットを新しい順に返します。形式は { data, nextCursor } です。 |
POST | /v1/palettes | { name, colors, description? } | パレットを作成します。201 を返します。色は大文字で保存されます。 |
GET | /v1/palettes/:id | なし | 1 つのパレットです。 |
PATCH | /v1/palettes/:id | name、colors、description のいずれか | 送ったフィールドだけが書き込まれます。description: null でクリアします。 |
DELETE | /v1/palettes/:id | なし | { success: true } を返します。 |
GET | /v1/moodboards | limit、cursor | 自分のムードボードを新しい順に返します。形式は { data, nextCursor } です。 |
POST | /v1/moodboards | { name, description?, images } | ムードボードを作成します。201 を返します。 |
GET | /v1/moodboards/:id | なし | 1 つのムードボードです。 |
PATCH | /v1/moodboards/:id | name、description、images のいずれか | 送ったフィールドだけが書き込まれます。images は、すべての画像を置き換えます。 |
DELETE | /v1/moodboards/:id | なし | { success: true } を返します。リンクされた画像には影響しません。 |
- ムードボードの画像はリンクで、コピーではありません。各
urlは、localhostやプライベートネットワークではないhttpまたはhttpsのアドレスで、最大 2,048 文字です。キャプションは最大 200 文字です。削除した画像や、プランのメディア保持期間によって削除された画像は、ムードボードからもなくなります。 nextCursorは不透明なトークンです。次のページを取得するには、cursorとして渡します。最後のページではnullです。- 自分だけのものです。ほかの人のパレットやムードボードには、存在しないものと同じく
404が返されます。 - スコープ:OAuth アプリのトークンでは、読み取りに
assets:readが、書き込みにassets:writeが必要です。書き込みは 1 分あたり 30 回までです。 - 同じルートは、SDK(
client.palettes、client.moodboards)、CLI(nodaro palettes、nodaro moodboards)、MCP のツールlist_palettes、save_palette、list_moodboards、save_moodboardにもあります。MCP のgenerate_imageはpalette_idとmoodboard_idを受け付けます。MCP には削除の操作はありません。
実行に渡るもの
- パレットは、
[style]セクションのフィルムの行、つまり組み込みのカラールックが入る場所に、color palette: <name> <hex>, …を追加します。各色には、いちばん近い日常的な色名と正確な 16 進コードが付きます。モデルは名前の付いた色のほうに、より確実に従うからです。パレットのメモは、プロンプトに追加されません。 - ムードボードは、組み込みのスタイルが入る場所に、その説明を 1 行で追加します。説明がない場合は、画像だけが送られます。
- ほかの演出の一節と同じく、プロンプトがモデルの上限を超えると、これらが最初に削られます。
- ムードボードの画像は、リファレンス画像としてモデルに送られます。各画像には、被写体や構図ではなく、色、光、質感、雰囲気をそこから取り入れるようモデルに伝える短い一文が付きます。キャプションがある場合は、それも追加されます。
- 自分のリファレンスが先です。自分で送った画像は、その位置と番号を保ちます。ムードボードの画像は、それらのあとに残ったリファレンスの枠だけを埋めます。
- モデルが受け付ける枚数を超えることはありません。収まらない画像は、ムードボードの順番に従って送られず、レスポンスには
moodboard_images_not_sentの警告が含まれます。リファレンス画像を受け付けないモデルには画像は送られませんが、説明は入ります。 - 料金:画像はリファレンスとして数えられるので、実行の料金は、同じ枚数のリファレンスを使うほかの実行と同じです。実行前に確認される料金と確保される料金では、同じ画像、つまり実際に送られる画像が数えられます。
aspectRatio: "auto"は、実行が最初に送る画像の形を保ちます。自分の画像を送らない場合は、ムードボードの最初の画像がそれにあたります。- ジョブには、コピーではなく ID が保存されます。もう一度実行すると、その時点のパレットやムードボードが使われます。
エラーと上限
| ステータス | コード | 状況 |
|---|---|---|
400 | validation_error | palette: や moodboard: の後に uuid がない、colorLook 以外のキーにパレットを指定した、style 以外のキーにムードボードを指定した、同じキーでほかの値と組み合わせた、または presetId も送ったリクエストです。field がキーを示します。 |
404 | direction_not_found | パレットやムードボードが自分のものではないか、もう存在しません。field は direction.colorLook または direction.style です。 |
どちらのレスポンスも、何かが作成または請求される前に返されます。パレットとムードボードは generate-image でのみ使えます。POST /v1/generate-video と POST /v1/text-to-video では、指定すると 400 validation_error が返されます。保存されたワークフローでは、direction でパレットやムードボードを指定した画像生成ノードは、ワークフローを実行するたびに解決されます。
ID による被写体の指定
subject は、ショットに誰が写っているかについての、同じ考え方です。人物、そのスタイリング、フレーム内の小道具です。POST /v1/generate-image、POST /v1/generate-video、POST /v1/text-to-video、POST /v1/generate-character、POST /v1/generate-creature が受け付けます。
{
"prompt": "on the seawall at dusk",
"provider": "nano-banana-pro",
"subject": {
"type": "woman",
"age": "age-30s",
"ethnicity": "east-asian",
"hairBase": "base-short-straight",
"makeup": "makeup-smoky",
"outerwear": "outerwear-trench",
"heldProp": "smartphone"
}
}- キーは、人物とスタイリングピッカーのフィールドです。
type、age、ethnicity、faceShape、hairColor、skinTone、makeup、outfit、outerwear、footwearなどで、これに加えて 3 つの小道具のキー、heldProp(手に持つ小道具)、material(素材)、animal(動物)があります。GET /v1/picker-catalogs/personと/stylingに、すべてのフィールドと ID が一覧表示されます。 subjectとdirectionは、決して重なりません。それぞれのキーは別々なので、1 つの選択が 2 つの一節を追加することはありません。poseはdirectionに属します。customAgeは、数値を指定する唯一のフィールドです。正確な年齢を指定するには、"age": "age-custom"と一緒に"customAge": 34を送信します。値は四捨五入され、0〜120 の範囲に保たれます。- リストには、キーごとに上限があります。
jewelry、wardrobeState、distinctiveFeatureは 3 個までです。ethnicity、regionalAesthetic、hairColor、eyeColor、lipState、eyeState、skinTexture、hairState、heldProp、materialは 2 個までです。animalを含む、それ以外のすべてのキーは 1 個までです。それを超える ID は取り除かれます。 - 拒否される上限:1 つのキーに 8 個を超えるエントリー、100 文字を超える ID、128 個を超えるキー、64 文字を超えるキーは、いずれも
400 validation_errorになります。 - 不明なキーは取り除かれ、不明な ID は読み飛ばされます。ジョブの
input_data.subjectには、実際に使われた ID がそのまま記録されます。 - subject の一節は、自分の文章の一部です。direction の一節より前に置かれ、
[style]セクションに入ることはありません。人物が 1 つの一節に、スタイリングがもう 1 つの一節になり、重なる選択は 1 回だけ書き込まれます。画像のルートでは、それぞれの選択が完全な一節を追加しますが、動画のルートでは短い用語だけを追加します。開始フレームに、すでに被写体が誰であるかが写っているためです。 POST /v1/generate-characterとPOST /v1/generate-creatureでは、subjectはポートレートに誰が写るかを指定します。文言は、seedPromptまたはdescriptionと、その行自身の人物と衣装の選択のすぐ後に置かれ、両方が同じ文言で持つ選択は 1 回だけ書き込まれます。この 2 つのルートは静止画の文言を使い、一節を短くすることはありません。キャラクターを参照してください。
生成セッション
画像、動画、音楽の作成ツールのように API で構築した作成ツールは、作業をプロジェクト内のセッションに保存できます。プロジェクトはセッションを持ち、各セッションはアイテムを持ちます。同じセッションがすべてのデバイスに表示され、アプリ側で何かを保存する必要はありません。
# 1. Open a session, optionally inside one of your projects.
SESSION=$(curl -s -X POST "https://app.nodaro.ai/v1/sessions" \
-H "Authorization: Bearer $NODARO_API_KEY" -H "Content-Type: application/json" \
-d '{"projectId": "<project-id>", "tool": "create-image", "title": "Beach"}' | jq -r .data.id)
# 2. Generate inside it: send sessionId beside the usual settings.
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 red car\", \"sessionId\": \"$SESSION\", \"origin\": \"create-image\"}"
# 3. Read the session's feed, newest first.
curl -s "https://app.nodaro.ai/v1/sessions/$SESSION/items" -H "Authorization: Bearer $NODARO_API_KEY"| メソッド | パス | 内容 |
|---|---|---|
POST | /v1/sessions | セッションを作成します。ボディは、tool(必須。小文字、数字、ダッシュの最大 40 文字)、projectId(任意。自分のプロジェクトの 1 つ)、title(任意。最大 200 文字)です。 |
GET | /v1/sessions | 自分のセッションを新しい順に返します。クエリは projectId(プロジェクトのないセッションは none)、tool、includeArchived=true、limit(1〜100、デフォルトは 50)、cursor です。各セッションは、itemCount(有効なアイテムの数)、removedCount(ゴミ箱にあるアイテムの数)、coverJobId、最大 4 件の previewUrls を持ちます。previewUrls は、カバーが設定されていればその画像が先頭で、続いて最新の完了したアイテムの画像です。 |
GET | /v1/sessions/:id | 1 つのセッションです。 |
PATCH | /v1/sessions/:id | title(null は無題)、archived、coverJobId を変更します。coverJobId は、プレビューの先頭にするセッションのアイテムの 1 つです(このセッションのアイテムでない場合は 404)。null で自動に戻ります。セッションのプロジェクトは、作成時に固定されます。 |
DELETE | /v1/sessions/:id | セッションとそのリンクを削除します。ジョブは残り、それを持つほかのすべてのセッションにも残ります。 |
GET | /v1/sessions/:id/items | フィードです。セッションで作ったものもインポートしたものも、有効なすべてのアイテムを新しい順に返します。removed=true を付けると、代わりにセッションから外したアイテム(このセッションのゴミ箱の分)を、外した時刻の新しい順に返します。各アイテムは、jobId、addedAt、removedAt(有効なアイテムでは null)、imported、importedFrom { sessionId, title } と、GET /v1/jobs/:id が返す形の job を持ちます。ジョブを削除したアイテムは、どちらの一覧にも入りません。limit と cursor でページを取得します。 |
POST | /v1/sessions/:id/items | { "jobIds": [...] } で 1〜100 件のジョブを、コピーではなくリンクとしてインポートします。いずれかの ID が自分のジョブでない場合や、削除済みの場合は、何もインポートされません(404)。セッションから外したアイテムは、元の位置に戻ります。{ imported, requested } を返します。 |
DELETE | /v1/sessions/:id/items/:jobId | このセッションからアイテムを 1 件取り除きます。アイテムはゴミ箱に移り、復元するか完全に削除するまで残ります。自動では何も削除されません。移るのはリンクだけで、ジョブと、それを持つほかのすべてのセッションは残ります。?forever=true を付けると、すでに取り除いたアイテムを完全に削除します。この場合もジョブは残ります。有効なアイテムには 409 not_in_trash を返します。 |
POST | /v1/sessions/:id/items/:jobId/restore | 取り除いたアイテムを、元の位置に戻します。 |
POST | /v1/sessions/:id/items/move | { "jobIds": [...], "fromSessionId": "…" } で 1〜100 件のアイテムを、1 回のトランザクションでこのセッションに移します。このセッションがアイテムを受け取り、移動元のセッションはそれらを取り除いたアイテムとして保持するので、移動元のゴミ箱から移動を取り消せます。いずれかの ID が fromSessionId の有効なアイテムでない場合は、何も移動されません(404)。{ moved } を返します。 |
- ジョブを作成するすべてのルートが
sessionIdを受け付けます。generate-image、generate-video、text-to-video、text-to-speech、generate-musicなどです。自分のセッションで、リクエストとワークスペースの境界の同じ側にある必要があります。そうでない場合、リクエストには404が返され、何も作成も請求もされません。ワークフローの実行が、セッションに整理されることはありません。 - ジョブの
session_idは、ジョブの作成時に 1 回だけ設定されます。GET /v1/jobs/:idとGET /v1/jobsに表示されます。 - ジョブを作成するすべてのルートは、
originも受け付けます。自分のアプリのスラッグです。ジョブはそれをinput_data.originに保存し、GET /v1/jobs?origin=で絞り込めます。スラッグではない値には400 validation_errorが返され、何も作成も請求もされません。 - 作業を別のプロジェクトに移すには、
POST /v1/sessions/:id/items/moveで、アイテムをそのプロジェクトのセッションに移します。セッションのプロジェクトは固定されているので、アイテムのプロジェクトを変えるにはこの方法を使います。両方のプロジェクトにアイテムを残すには、代わりにインポートします。 - ジョブが今どこにあるか:
GET /v1/jobsは、projectId=<id>(そのプロジェクトのセッションが現在保持しているジョブ)と、projectId=none(プロジェクトのないセッションが保持しているジョブ)を受け付けます。inSession=false(現在どのセッションにも保持されていないジョブ。一般)とinSession=trueも受け付けます。いくつのセッションが保持していても、各ジョブは 1 回だけ表示されます。withSessions=trueを付けると、各ジョブにsessions: [{ id, title, projectId }]が加わるので、「このプロジェクトのすべて」の表示を作れます。projectIdとinSession=falseは組み合わせられません(400)。これらの絞り込みは、type、statusなどのほかの絞り込みと組み合わせられます。 - ゴミ箱:取り除いたアイテムも削除したジョブも、ゴミ箱に移ります。ゴミ箱を参照してください。
- スコープ:OAuth アプリのトークンでは、セッションの読み取りに
jobs:readが必要です。作成、編集、インポート、取り除く操作にはassets:writeが必要で、生成でsessionIdを送る場合も同じです。一部のワークフローに制限された個人用 API トークンは、これらのルートを使えません。
実行の見積もり
POST /v1/quote は、ノードの実行を開始する前に、その実行で確保される額を返します。ノードタイプと、実行のルートに送るのとまったく同じボディを送信します。サーバーは、実行のルート自体のコードで料金を計算します。ボディの検証、リファレンスのクリップの測定、クレジット ID、計算方法はすべて同じです。そのため、見積もりは実行で確保される額と一致します。何も開始されず、課金もされません。
- 利用できる場所:Nodaro Cloud のみです。このルートには認証が必要で、1 分あたり 30 リクエストまで使えます。
- 対応するタイプ:
text-to-video、generate-video、video-to-video、video-upscale、edit-image(すべての編集モデル)、ai-avatar、cinematic-avatar、switchx、split-into-layersです。video-upscaleでの Seedance 2.5 のドラフトの 1080p 仕上げは、ドラフトと、その作成に使ったクリップから料金が計算されます。ほかのタイプは400 quote_unsupportedになり、対応するタイプが一覧表示されます。 - アバターと SwitchX:
ai-avatarは、測定した音声の長さの区分で料金が計算されます。測定は実行と同じ方法で行われます。テキストモードでは、台本の推定の長さの区分で計算されます。読み込めない音声は、実行自体の400になります。cinematic-avatarは正確な解像度と長さで料金が計算され、長さを自動設定では上限の 15 秒で計算されます。switchxは、実行と同じ方法で測定したクリップのフレーム数のブロック段階で料金が計算され、フレーム数を読み込めないときは 240 フレームの段階で計算されます。 - Seedance の編集:
video-to-videoでの Seedance の編集は、送られるすべてのクリップ(videoUrlとreferenceVideoUrls)で料金が計算されます。リファレンスのリストについては、動画から動画を参照してください。 - SDK:
client.nodes.quote(type, params)。
{
"type": "text-to-video",
"params": {
"prompt": "edit {video:1} as follows: make it black and white",
"provider": "seedance-2-5",
"duration": -1,
"aspectRatio": "adaptive",
"referenceVideoUrls": ["https://…/clip.mp4"]
}
}応答は { "data": { identifier, reserve, expected?, adjustments, warnings } } です。
| フィールド | 意味 |
|---|---|
identifier | 実行が課金されるクレジット ID です。 |
reserve | 実行の開始時に確保されるクレジットです。 |
expected | 測定した入力からわかる場合に、実行に実際にかかるはずのクレジットです。Seedance のリファレンス動画の実行は、最悪の場合で確保されます。入力の秒数に、指定した長さと最長のクリップのうち長いほうを加えた額です。長さが自動で、すべてのクリップを計測できた場合は、入力の秒数に、最長のクリップの長さを 1 秒単位に切り上げて 1 秒足した長さを加えた額です。referenceTaskType: "reference" を宣言した実行は、代わりにモデルの最長の出力で確保されます。expected は、入力に、最も可能性の高いレンダリングの長さを加えた額です。長さが自動の編集では元のクリップの長さ、それ以外では指定した秒数です。reserve を上回ることはありません。 |
adjustments | { code, message, credits? } のリストで、料金がその額になる理由です。ref_video_length(クリップの長さで料金を計算)、extra_reference_images(MiniMax H3 の 6 枚目以降の画像)、auto_duration、loop_trim_addon と voiced_audio_addon(それぞれのクレジット付き)、params_adjusted(解像度や比率を、モデルが提供するものに合わせた)、output_size(画像のアップスケールを、作る画像のサイズで料金計算した)、max_images(レイヤーに分割で、実行が返せる最大の画像数で料金計算した)があります。 |
warnings | { code, message } のリストです。settles_to_actual(reserve は実行にかかりうる最大額で、実行は届けた分で課金され、残りは返還される)、ref_video_unmeasured(クリップを測定できなかったため、モデルが受け付ける最長のクリップとして料金を計算した)、image_size_unmeasured(実行前に画像のサイズを読み取れなかった)があります。 |
settles_to_actual の警告がない場合、reserve は、実行が完了したときに課金される額です。
- 無効なボディには、実行のルート自体の
400が返されます。実行が拒否するクリップには400 video_too_longが返されます。このデプロイ環境が提供していないモデルには、実行と同じ403 model_not_availableが返され、提供されていないノードには、実行と同じ403 node_not_availableが返されます。 - アップロードや生成した結果など、Nodaro に保存されたクリップは、一度測定すると 15 分間記憶されます。同じボディで見積もってから実行すると、測定は 1 回で済みます。
- 見積もりで確認するのはボディと料金で、残高やプランは確認しません。実行では、それでも
402が返されることがあります。実行だけが行う確認もいくつかあり、見積もったボディが拒否されることもあります。たとえば、開始フレームが必要なモデルです。
Nodaro Image Upscale(edit-image で provider: "nodaro-image-upscale")は、作る画像のサイズで料金が決まります。その見積もりは、送った画像を読み取り、実行と同じように確認して測定します。何も保存せず、そのサイズの正確な料金を返します。クレジット ID は出力の段階を示します。たとえば 1024 × 1024 の画像を upscaleFactor: "2" にすると nodaro-image-upscale:2K です。サイズを読み取れない画像は確保額で見積もられ、image_size_unmeasured と settles_to_actual の警告が付きます。
- ほかのサイトへのリンクは、このデプロイ環境のリンク取り込みの設定に従い、オフの場合は
403 link_imports_disabledになります。 - 大きすぎる画像や読み取れない画像など、実行が拒否する画像には、実行自体の
400が返されます。 - 外部の画像が届くまでの時間は 15 秒です。それを過ぎると、見積もりは
503 input_timed_outを返します。もう一度試すか、画像をアップロードしてください。 - ほかの編集モデルは、それぞれの料金で見積もられます。倍率で料金が決まるアップスケーラーは、出力が非常に大きいと高くなることがあり、
output_sizeの調整がそれを示します。
レイヤーに分割は、確保額で見積もられます。実行が返せる最大の画像数(ベースを含めて maxLayers + 1)を、そのサイズの料金で計算した額です。実行は返した画像の分だけ課金されます。そのため見積もりには、settles_to_actual の警告と、確保する画像数を示す max_images の調整が付きます。
{ "type": "split-into-layers", "params": { "imageUrl": "https://…/poster.png", "maxLayers": 5, "size": "1K" } }この見積もりの identifier は split-into-layers:1k:6 です。5 枚のレイヤーとベースを、1K と 1.5K に共通の料金で計算した額です。
ノードを調べる
GET /v1/nodes は、サーバーが認識するすべてのノードタイプを一覧表示し、GET /v1/nodes/:type は 1 つを返します。どちらも公開されており、トークンは不要で、5 分間キャッシュされます。不明なタイプは 404 not_found を返します。
curl -s https://app.nodaro.ai/v1/nodes/generate-image | jq .dataconst { data: nodes } = await client.nodes.list()
const imageNodes = nodes.filter((n) => n.category === 'ai-image')
const { data: generateImage } = await client.nodes.get('generate-image')
console.log(generateImage.providers)nodaro nodes list --category ai-image
nodaro nodes get generate-image{
"data": {
"type": "generate-image",
"label": "Generate Image",
"category": "ai-image",
"description": "Generate an image from a text prompt using an AI provider.",
"outputType": "image",
"creditCost": "3-682",
"providers": ["nano-banana-pro", "gpt-image-2", "gpt-image-2-5-flare", "seedream-5-pro", "z-image"],
"capabilities": ["supports-reference-image", "supports-aspect-ratio"],
"inputSchema": {
"fields": [
{ "key": "prompt", "type": "text", "required": true },
{ "key": "provider", "type": "select", "options": ["nano-banana-pro", "gpt-image-2"] },
{ "key": "aspectRatio", "type": "select" },
{ "key": "promptPrefix", "type": "text" },
{ "key": "promptSuffix", "type": "text" }
]
}
}
}| フィールド | 意味 |
|---|---|
type | ノードタイプです。ほとんどのノードタイプでは、ルートの POST /v1/<type> にもなります。 |
label、category、description | エディターが、このノードをどう名付け、どうグループ分けするかです。 |
outputType | text、image、video、audio、data、none のいずれかです。 |
creditCost | ノードのクレジット料金、またはその範囲です。実行に請求される料金で、ノードの実行ボタンと同じ数値です。動画のトリミング、動画をループ、動画を結合では、代わりに 5 秒の 1 段階分の料金で、実行の料金はこれに段階の数を掛けた額です。Nodaro Cloud のみです。クレジットのないエディションでは省かれます。 |
estimate | creditCost が見積もりの場合は true です。見積もりは、従量課金の LLM ノードのデフォルトのモデルでの一般的な呼び出しの料金です。実行には実際の使用分が請求されるので、数値は ≈N と表示してください。ベストを選択は、estimate 付きの "0-N" の範囲を返します。無料の戦略から、AI 審査員の一般的な呼び出しまでの範囲です。固定料金の場合は含まれません。デフォルトのモデルにまだ料金のない従量課金の LLM ノードは creditCost: "unpriced" を返し、そのモデルでの実行は拒否されます。エラーを参照してください。 |
creditRate | ノード独自の単位ごとに課金されるノードで、creditCost が数値ではなく単語の場合に使います。現在は話者フレームで、creditCost は "per-1000-frames" です。オブジェクトは { identifier, unit, creditsPerUnit, minUnits, rounding, note } です。creditsPerUnit は 1 単位の正確な料金で、丸められていません。rounding: "ceil-run-total" の場合、N 単位(最低 minUnits)の実行には ceil(N × creditsPerUnit) が課金され、切り上げは 1 回だけです。/v1/credits/model-cost の 1 単位の料金を掛け算しないでください。 |
providers | ノードが provider に受け付けるモデル ID です。 |
capabilities | supports-reference-image のような、機能のフラグです。 |
inputSchema.fields | ノードの設定です。型、必須かどうか、選択肢を含みます。 |
プロンプトを受け付けるすべてのノードには、promptPrefix と promptSuffix も一覧表示されます。プロンプトの前後に追加されるテキストです。プロンプトの前後のテキストを参照してください。モデルごとの上限があるノードには、追加のフィールドがあります。
| フィールド | 意味 |
|---|---|
maxDurationSec | ノードが受け付ける、最長の長さです。 |
sparseProviders | セグメントの長さの選択肢が少ないモデルです。その間の値は、最も近いものに変更されます。 |
providerResolutions | 各モデルの解像度です。たとえば { "minimax-h3": ["2K", "768P"] } です。 |
providerResolutionWire | 各解像度について送信する、正確な値です。たとえば MiniMax H3 の安いティアでは、768p ではなく 768P です。 |
soundtrack | 動画生成 Proで、サーバーが元の音声の soundtrack 入力を受け付けることを示します。 |
このディスクリプターのフィールドは今後も増えていくため、知らないフィールドは無視してください。同じデータが、ノードリファレンスのもとにもなっています。
モデルを調べる
GET /v1/models は、種類と開発元でグループ分けされたモデルカタログを返します。公開されており、5 分間キャッシュされ、MCP の list_models ツールが返すのと同じデータです。
このデプロイ環境が提供していないモデルは一覧に含まれません。管理者がオフにしたモデルも同様です。同じ設定により、そのモデルの実行は 403 model_not_available で拒否されます。一覧を 5 分間保持するクライアントは、そのようなモデルを指定してしまう可能性があります。
curl -s "https://app.nodaro.ai/v1/models?kind=video&mode=i2v" | jq '.totalModels'const catalog = await client.models.list({ kind: 'video', mode: 'i2v' })
for (const section of catalog.sections)
for (const family of section.families)
for (const m of family.models) console.log(m.id)nodaro models list --kind video --mode i2vレスポンスは { sections, recommendations, totalModels } です。各モデルは、そのメーカーを示し、メーカーのマークを持ちます。ただし、インスタンスが独自のラベルで提供するモデルは例外です。そのようなモデルはメーカーを示さず、maker はなく、logoUrl は null です。
| フィールド | 型 | 意味 |
|---|---|---|
maker | { id, name }。インスタンス独自のラベルで提供されるモデルにはない | モデルを作った会社です。id は変わらず、会社ごとに 1 つで、google、black-forest-labs、bytedance のように小文字とハイフンで書かれます。自分のアセットはこれをキーにしてください。新しいサーバーではメーカーが追加されることがあるので、知らない ID にも対応してください。モデルがグループ化される family と同じとは限りません。 |
logoUrl | string または null | このサーバーのメディア CDN にある、メーカーの公式マークの SVG です。サーバーが公開していない場合は null です。その場合は、メーカーの名前や頭文字など、代わりの表示を描画してください。アドレスはそのまま使ってください。ファイルのバージョンが含まれているので、差し替えられたマークは新しいアドレスで届きます。 |
GET /v1/model-makers は、メーカーだけを返します。マークを描画するだけで、カタログが不要なアプリ向けです。応答は { makers: [{ id, name, logoUrl }] } で、プラットフォームが知っているすべてのメーカーを含みます。フィールドは上記と同じなので、2 つのルートの内容が食い違うことはありません。このルートは公開されており、GET /v1/models と同じく 5 分間キャッシュされます。提供されているモデルがないメーカーも一覧に含まれます。
MCP の list_models ツールは、maker を含みますが、logoUrl は含みません。
各モデルは、ほかにもその機能(modes、features、aspectRatios、resolutions、qualities、backgrounds、durations、それに下記のサイズのルールと出力形式)、Nodaro Cloud でのバリアントごとのクレジット pricing、簡潔な promptTips、そして doctrineCovered を持ちます。doctrineCovered は、そのモデルファミリーについて、出典のあるプロンプトガイドが存在する場合にだけ true になります。pricing のクレジットは実行に請求される料金で、エディターの実行ボタンと同じ数値です。リファレンスのタスクタイプを受け付ける動画モデルは、その値を referenceTaskTypes に示します。seedance-2-5 では ["reference", "edit", "extend"] で、ほかのモデルにはありません。
テキストから音声やダイアログのモデルなどの音声モデルは、音声を長さで課金する環境では、2 つ目の pricing 行 <model>:per-100-chars を持ちます。この行は、送信したテキストの 100 文字ごと(端数は切り上げ)の料金で、1 回の実行につき最低 8 単位です。リクエストは全体として料金が計算され、1 回だけ丸められるため、N × この行のクレジット(N = max(8, ceil(characters / 100)))は上限にすぎません。正確な料金は ID <model>:per-100-chars:<N>u で、POST /v1/credits/model-costs と GET /v1/credits/model-cost がこの ID に答えます。掛け算の結果ではなく、その数値で見積もってください。この行がない場合は、:<N>u の ID もすべてありません。モデルの定額の行で見積もってください。単位あたりで料金が決まる実行の正確な料金を参照してください。
一部の画像モデルは、特定のアスペクト比でレンダリングできるサイズが少なかったり、透明な背景を 1 つのサイズでしかレンダリングできなかったりします。また、いくつかのモデルは、サイズを指定しないリクエストがどのサイズになるかを宣言しています。そうしたモデルのエントリーは、次のフィールドでそれを示します。ほかのモデルや古いサーバーでは、これらのフィールドはありません。
| フィールド | 型 | 意味 |
|---|---|---|
defaultResolution | string | resolution を指定しないリクエストがなるサイズで、モデルが宣言している場合に resolutions と同じ表記で示されます。FLUX 3 Klein(flux-3-klein、flux-3-klein-i2i)では 1K、Seedream 5.5 と MiniMax H3 Image、およびそれらの -i2i 編集モデルでは 2K、PixVerse V6 Max では 720p です。resolutions の最初の項目がデフォルトだと決めつけず、このフィールドを読んでください。 |
resolutionsByAspectRatio | { [ratio]: string[] } | resolutions よりも少ないサイズでしかレンダリングしないアスペクト比と、その比率でレンダリングするサイズです。記載のない比率は、resolutions のすべてのサイズでレンダリングします。それより大きいサイズは、その比率がレンダリングする、それ以下で最大のサイズで実行・課金され、adjustments にそのことが示されます。 |
transparentResolution | string | 透明な背景をレンダリングする唯一のサイズです。ほかのサイズでの透明のリクエストは、このサイズで実行・課金されます。 |
backgroundOnlyAtTransparentResolution | true | モデルが背景の設定を受け付けるのは transparentResolution のときだけです。ほかのサイズでは、opaque は auto としてレンダリングされ、adjustments に報告されます。 |
GPT Image 2.5(gpt-image-2-5-flare、gpt-image-2-5-sunburst と、その -i2i 編集モデル)は、27:16、16:27、9:8、8:9 を 1K でしかレンダリングせず、透明な背景も 1K でレンダリングします。
{
"id": "gpt-image-2-5-flare",
"aspectRatios": ["auto", "1:1", "16:9", "9:16", "27:16", "16:27", "9:8", "8:9"],
"resolutions": ["1K", "2K", "4K"],
"resolutionsByAspectRatio": { "27:16": ["1K"], "16:27": ["1K"], "9:8": ["1K"], "8:9": ["1K"] },
"backgrounds": ["auto", "opaque", "transparent"],
"transparentResolution": "1K",
"backgroundOnlyAtTransparentResolution": true
}この例は、これらのフィールドだけを示しており、すべての比率は含みません。サイズのメニューは、選んだ比率が resolutionsByAspectRatio に記載されていればその値を、そうでなければ resolutions を表示します。GPT Image 2(gpt-image-2 と gpt-image-2-i2i)は resolutionsByAspectRatio を記載しません。auto と 1:1 を含め、対応するすべての比率を 1K、2K、4K でレンダリングします。GPT Image 2.6 Flare と Sunburst は transparentResolution: "1K" を記載し、resolutionsByAspectRatio は記載しません。
複数の種類のファイルを書き出すモデルは、その形式を記載します。ほかのモデルや古いサーバーでは、これらのフィールドはありません。
| フィールド | 型 | 意味 |
|---|---|---|
outputFormats | string[] | モデルが書き出すファイル(png、jpeg、webp、gif、svg)で、デフォルトが先頭です。outputFormat が受け付ける値です。 |
gifFrameSize | number | gif の場合:正方形の各フレームのピクセルサイズです。GIF は aspectRatio と resolution を無視します。 |
gifFrames | { min, max, default, values? } | gif の場合:gifFrames が受け付けるフレーム数です。min から max までの整数か、モデルが一部の値だけを受け付ける場合は values のいずれかです。 |
gifFrameDurationMs | { min, max, step, default } | gif の場合:各フレームの表示時間(ミリ秒)です。 |
svgLevels | string[] | svg の場合:svgLevel が受け付ける詳細さのレベルで、デフォルトが先頭です。 |
{
"id": "gpt-image-2-6-flare",
"outputFormats": ["png", "jpeg", "webp", "gif", "svg"],
"gifFrameSize": 512,
"gifFrames": { "min": 2, "max": 16, "default": 9 },
"gifFrameDurationMs": { "min": 20, "max": 2000, "step": 10, "default": 200 },
"svgLevels": ["standard", "detailed", "max"]
}| クエリ | 値 | 絞り込み対象 |
|---|---|---|
kind | image、video、audio のいずれか | メディアの種類 1 つ |
mode | たとえば t2i、i2v、t2v、tts、video-analysis | 操作 1 つ |
family | 開発元です。たとえば Google や Bytedance です | 開発元 1 つ |
featuredOnly | true | 注目のモデル |
モデルのページにも、同じカタログが載っています。
このデプロイメントが提供するもの
GET /v1/surface/availability は、サインインしている人にアプリが何を表示すべきかを返します。このデプロイメントがその人に提供するノードタイプ、モデル、Web Scrape のソース、ワールドです。GET /v1/nodes や GET /v1/models と違い、答えは問い合わせた人によって変わるので、Cache-Control: private, no-store 付きで送られます。トークンは任意で、サインインしていなければ一般ユーザーへの答えになります。スコープは要りません。
{
"nodes": { "denied": ["social-publish"], "hiddenFromUsers": [] },
"models": { "denied": ["flux-flex"], "restricted": true },
"webScrapeSources": { "denied": [], "hiddenFromUsers": [] },
"worlds": [
{ "id": "image", "enabled": true },
{ "id": "video", "enabled": false }
]
}| フィールド | 意味 |
|---|---|
nodes.denied | 提供されていないノードタイプです。保存や実行は 403 node_not_available で拒否されます。 |
nodes.hiddenFromUsers | 管理者以外には空です。管理者は使えても、デプロイメントのユーザーは使えないノードタイプです。 |
models.denied | このデプロイメントの誰にも提供されていないモデル ID です。実行すると 403 model_not_available が返されます。 |
models.restricted | デプロイメントが提供するモデルを制限している場合に true です。管理者がモデルをオフにしただけの場合、そのモデルは models.denied に記載されますが、この値は true になりません。true の場合、ワークフローエディターは、新しいノードをメニューが提供するモデルで始めます。このフィールドより古いサーバーでは省略されます。その場合は false として扱ってください。 |
webScrapeSources.denied、webScrapeSources.hiddenFromUsers | それを管理するノードとともに取り下げられた Web Scrape のソースで、上と同じ 2 つの見え方です。Instagram のソースは Instagram ノードに従います。 |
worlds | 共通のサイトヘッダーのすべてのワールドを、デプロイメントの表示順で並べたものです:explore、image、video、music、trends、motion、voice、app(ワークフローエディター)、studio。新しいサーバーではワールドが増えることがあるので、知らない ID にも対応してください。 |
worlds[].enabled | デプロイメントがそのワールドを通し、ワールドが実行するすべてのノードタイプを使える場合に true です。image は generate-image、video は generate-video と text-to-video、music は suno-generate、trends と motion は cast-swap、voice は voice-changer-pro を実行します。explore、app、studio は独自のノードを実行しません。 |
worlds が示すのは、デプロイメントの提供設定だけです。エディションがそもそもノードを提供するかどうかは、サーバーが決めます。どのワールドがどのノードを実行するかの表は、@nodaro/shared/runtime-config の WORLD_REQUIRED_NODE_TYPES として公開されています。SDK では client.surface.availability() です。
この応答が届く前や、応答を読み取れない場合、アプリは実行時設定にあるリスト、surface.nodes、surface.models、surface.worlds からデプロイメントを判断できます。@nodaro/shared/runtime-config の nodeListsWithhold、listsWithhold、worldOffered は、サーバーがこれらのリストに適用するのと同じ規則を適用します。ワークフローエディターはこの方法で動作します。
コンテンツフィルターが強制的にオンになっているモデル
GET /v1/provider-safety/locks は { "forcedOn": ["seedance-2"] } を返します。このデプロイメントがコンテンツフィルターを強制的にオンにしているモデルです。これらのモデルでフィルターの選択肢を出すクライアントは、オンのままロックして表示してください。強制されているフィルターがなければ、リストは空です。
ピッカーの値を調べる
クリエイティブコントロールのピッカーには、有効な ID の公開カタログがあります。direction と subject が取る値です。
| メソッド | パス | 返す内容 |
|---|---|---|
GET | /v1/picker-catalogs | すべてのピッカーです。nodeType、label、kind、そのフィールド、optionCount、imageCount です。画像をオフにしたデプロイメントでは、すべてのピッカーの imageCount が 0 です。 |
GET | /v1/picker-catalogs/:nodeType | 1 つのピッカーの選択肢です。?detail=full を付けると、各選択肢の description と promptHint(style の選択肢では、その画像向けの文言)が加わります。?category= は単一フィールドのピッカーを絞り込み、?field= は複数フィールドのピッカーの 1 つのフィールドを返します。 |
GET | /v1/catalogs | デプロイ環境が整備したとおりの、すべてのカタログを 1 回の呼び出しで返します。data が存在するのは、デプロイ環境がカタログパックを登録した場合か、独自のピッカー画像を表示する場合です。 |
POST | /v1/text-to-picker | 「AI Fill」(AI による自動入力)です。自由記述のシーンの説明から、多くのピッカーの ID を選びます。llmModel を指定しない場合、Gemini 3.8 Flash で実行します。呼び出しで使ったトークンに応じて、モデルの単価で課金されます。ピッカーカタログを参照してください。 |
すべての選択肢は、id、label、そしてプロンプトで使う短い言い回しである term を持ち、画像がある選択肢には imageUrl も付きます。デプロイメントは、サーフェスプロファイルの catalogs.images で画像をオフにできます。その場合、応答のどの選択肢にも imageUrl と imageSrcSet は含まれません。独自の画像を表示するデプロイメントは、imageLargeUrl を加えることがあります。ピッカーが選択肢を大きく表示する場所のための拡大画像です。独自の画像は、/brand/style/noir.webp のような、そのサイト上のパスであることがあります。このパスは、API を呼び出したアドレスを基準に解決してください。画像を参照してください。カタログは、@nodaro/prompts npm パッケージのデータとしても提供されます。完全な形については、ピッカーカタログを読んでください。ターミナルからは、nodaro pickers list、nodaro pickers get mood --full、nodaro pickers analyze "<text>" を使います。
構造化された LLM 出力
POST /v1/llm/structured は、1 回の言語モデルの呼び出しを実行します。その回答は、指定した JSON Schema に強制的に当てはめられ、検証されたうえで、オブジェクトとして返されます。呼び出しは、実際に使ったトークンに応じて、それを処理したレーンでのモデルの単価で課金されます。トークンには、システムプロンプト、入力、スキーマ、検証のための聞き直しとレーンのフォールバックのすべて、そして回答が含まれます。LLM 呼び出しの課金のしくみを参照してください。
- 呼び出しの前に、確保額が確保されます。これは、モデルの出力上限での 1 回目の試行の分です。残高が確保額より少ない場合は、
402(「最大 N クレジットが必要です。」)で拒否されます。 - 呼び出しの後、使った分が請求されます。これは通常、確保額より少なくなります。
- 見積もり:一般的な呼び出しの見積もりは、キー
llm-structured:<model>を指定したPOST /v1/credits/model-costsから得られます。見積もりなので、≈Nと表示してください。クレジットを参照してください。 - 失敗:プロバイダーが課金した失敗はその使用分が請求され、エラーに金額が表示されます。たとえば、再試行の後も検証に通らなかった回答、拒否、上限で途中で切れた回答です。プロバイダーが課金しなかった失敗は返還されます。
Claude Fable 5 は、このルートで提供されています。
{
"system": "You write production plans.",
"input": "A rainy chase through Rome.",
"jsonSchema": {
"type": "object",
"properties": { "title": { "type": "string" } },
"required": ["title"]
}
}回答は { jobId, output, usage: { inputTokens, outputTokens } } で、output が、指定したスキーマの形になります。
- フィールド:
system、input、jsonSchemaが必須で、任意でschemaName(最大 64 文字)、llmModel、reasoningEffort、maxRetries、origin、advancedMode、temperature、maxTokensを指定できます。systemは最大 200,000 文字で、スキーマが使う語彙を入れる余裕があります。inputは 1〜100,000 文字です。 - モデル:
llmModelを指定しない場合、呼び出しは Gemini 3.6 Flash で実行されます。 - スキーマ:ルートは、単純なオブジェクトのスキーマである必要があり、最大 64 KB、深さ 20 レベルまでです。
properties、required、additionalProperties、items、基本の型、enum、const、数値と長さの範囲、multipleOf、exclusiveMinimum、descriptionを使えます。anyOfとoneOfは、ルートより下でのみ使えます。not、if、then、else、dependent系のキーワード、外部の$ref、ルートでのコンビネーターは400を返します。ルートより下のrequired分岐によるanyOfは受け付けられますが、強制はされません。フィールドをまたぐ規則は、自分で確認してください。 - 再試行:
maxRetriesは 0〜3 で、デフォルトは 2 です。無効な回答を、検証エラーとともにモデルへ差し戻す回数です。 - サンプリング:
maxTokensはすべての呼び出しに適用され、モデル自体の上限を超えることはできません。temperatureは、advancedMode: trueも一緒に送信しない限り無視されます。advancedMode: trueでは、呼び出しがモデル開発元自身の API 上で、そのレーンの単価で実行されます。 - 所要時間:この呼び出しは同期的で、数分かかることがあります。各試行は、2 つの経路のそれぞれで最大 240 秒かかることがあるため、最悪の場合、デフォルトの
maxRetriesでは 24 分、最大値では 32 分かかります。HTTP クライアントのタイムアウトを延ばすか、下記のジョブの形式を使ってください。SDK のデフォルトのtimeoutMsである 60 秒では短すぎます。 - エラー:
400 validation_error、400 advanced_mode_unavailable、401、402、500 internal_error、再試行を使い切った後の502 llm_error、502 advanced_mode_unavailable、503 provider_unavailableです。advanced_mode_unavailableによる拒否については、上記のadvancedModeを参照してください。確保額に関するコードが、さらに 2 つあります。409 job_cancelledと503 job_start_failedです。エラーを参照してください。
SDK では、client.llm.structured(body) を呼び出します。
ジョブとして実行する
POST /v1/llm/structured/jobs は、同じボディを受け取り、すぐに { jobId } を返します。GET /v1/jobs/:id/status をポーリングしてください。completed になると、output_data は { output, inputTokens, outputTokens } になり、failed になると、error_message に理由が示されます。作成したドラフトは、GET /v1/jobs?type=llm-structured&origin=<your app> でもう一度見つけられます。3 つの追加フィールドを受け付けます。
label:ジョブの表示名で、最大 120 文字です。videoUrl:動画からドラフトを作ります。動画はまず、自分が所有する別のジョブとして、動画分析の料金で分析され、その分析結果がinputに追加されます。実行中は、output_data.stageがanalyzing、続いてdraftingになります。videoAnalysis:その分析のための{ llmModel?, selectionMode? }です。
ドラフトの確保額は、ジョブの作成時に llm-structured:<model>(プロバイダー自身の API では :direct 付き)で確保されます。その後、ジョブには、ドラフトで使った分が請求されます。POST /v1/jobs/:id/cancel でドラフトをキャンセルすると、実行中の分析もキャンセルされます。分析が拒否されると、ドラフトのために確保されていたクレジットはすべて返還されます。言語モデルの呼び出しを nodaro.ai に送るインストール環境では、ジョブの形式は 503 provider_unavailable を返します。その場合は、同期呼び出しを使ってください。SDK では、client.llm.structuredJob(body) を呼び出します。
よくある質問
Nodaro API で画像を生成するにはどうすればよいですか?
prompt と provider を指定して POST /v1/generate-image を送信します。レスポンスには jobId が含まれます。ステータスが completed になるまで GET /v1/jobs/:id/status をポーリングし、output_data.imageUrl を読み取ります。SDK では、client.nodes.runAndWait がこの両方のステップを行います。
API から実行できるノードはどれですか?
GET /v1/nodes が一覧表示する、すべてのノードタイプです。ルートは POST /v1/ の後にノードタイプを付けたもので、ノードの設定を JSON のボディとして送ります。一部のテキストノードは、/v1/llm-chat/generate のような、より長いパスを使います。
direction オブジェクトとは何ですか?
画像や動画の生成と一緒に送る、ピッカー ID をまとめたフラットなマップです。たとえば { "shotSize": "wide-shot", "timeOfDay": "golden-hour" } です。Nodaro は、各 ID に対応する検証済みの言い回しをプロンプトに書き込みます。有効な ID は GET /v1/picker-catalogs から取得します。
API でキャラクターの一貫性を保つにはどうすればよいですか?
キャラクターの画像を、source に wired-character、defaultName にキャラクターの名前を指定して、connectedReferences で送信します。ルートは画像を添付し、エディターと同じように、アイデンティティの指示をプロンプトに書き込みます。
検出用のエンドポイントにトークンは必要ですか?
いいえ。GET /v1/nodes、GET /v1/models、GET /v1/picker-catalogs、GET /v1/catalogs は公開されており、5 分間キャッシュされます。公開されるのはカタログのデータだけで、アカウントに関する情報は含まれません。
プロンプトと direction の ID を合わせた長さが、モデルの上限を超えるとどうなりますか?
Nodaro は、まず direction の一節を、末尾から 1 つずつ、プロンプトが収まるまで取り除きます。subject の一節はそれよりも後に取り除かれ、あなた自身の文章とリファレンスは、それらのために取り除かれることはありません。
関連ページ
ジョブ
ワークフロー
ピッカーカタログ
画像生成
Nodaro の AI モデル
最終更新