ピッカー、プリセット、プロンプト

ピッカーは、ムード（Mood）やレンズ（Lens）といった、クリエイティブコントロールのノードです。選んだ内容が、検証済みの言い回しをプロンプトに加えます。client.pickerCatalogs と client.catalogs は、各ピッカーの有効な選択肢を返し、analyzeText() は、シーンの説明からピッカーを埋めます。client.presets は保存されたノードの設定を読み取り、client.promptHelper はプロンプトウィザードで、どの生成ノードのプロンプトも改善します。概念については、クリエイティブコントロールとピッカーカタログを参照してください。

メソッド

client.pickerCatalogs

ピッカーのノードの選択肢の一覧です。どちらの読み取りメソッドも公開されていて、トークンは不要で、サーバーが 5 分間キャッシュできます。コードが @nodaro/shared をインポートできる場合、同じカタログが型付きデータとしてそこにも含まれています。これらのメソッドは、それを同梱できないクライアント向けです。

pickerCatalogs.list()

すべてのピッカーを一覧表示します（GET /v1/picker-catalogs）。

list(): Promise<{ data: PickerCatalogSummary[] }>

const { data: pickers } = await client.pickerCatalogs.list()
const mood = pickers.find((p) => p.nodeType === "mood")

各エントリーには、nodeType、label、catalogId、kind（single または multi）、単一次元のピッカーでは valueField、複数次元のピッカーでは fields、optionCount、そして画像がある選択肢の数である imageCount があります。

pickerCatalogs.get(nodeType, opts?)

1 つのピッカーの選択肢を読み取ります（GET /v1/picker-catalogs/:nodeType）。ムードのような単一次元のピッカーには options があります。人物のような複数次元のピッカーには dimensions があり、それぞれ { field, label, options } です。いくつかの単一次元のピッカーには、メインの選択のほかに追加の設定もあります。transition と character-fx には position、duration、intensity があり、character-motion には position と pace があります。

get(nodeType: string, opts?: { detail?: "compact" | "full"; category?: string; field?: string }): Promise<{ data: PickerCatalog }>

const { data } = await client.pickerCatalogs.get("mood", { detail: "full" })
const serene = data.options?.find((o) => o.id === "serene")
console.log(serene?.term)       // the short phrase, added in Compact mode
console.log(serene?.promptHint) // the full sentence, added in Full mode

不明なノードタイプには NotFoundError をスローします。

label を表示し、term を追加します。どちらの詳細レベルでも、すべての選択肢に term があります。プロンプトに入れる、短い専門用語です。label は表示専用です。一方からもう一方を導き出さないでください。auto や none のように何も追加しない選択肢は、term が空です。

画像。画像がある選択肢には、どちらの詳細レベルでも、絶対 URL の imageUrl があります。person と styling は sections も返します。エディターが設定をグループ分けするトピックで、それぞれ { label, fields, imageUrl? } です。写真と、音楽やボイスのアートは、インストール環境自身が配信します。レンダリング済みのルックのプレビューは Nodaro CDN から配信され、返すのは Nodaro Cloud だけです。ファイル名にはコンテンツのハッシュが含まれるため、画像は期限なくキャッシュできます。

const { data: person } = await client.pickerCatalogs.get("person")
for (const section of person.sections ?? []) {
  const settings = person.dimensions?.filter((d) => section.fields.includes(d.field)) ?? []
  for (const setting of settings) {
    for (const option of setting.options) renderTile(option.label, option.imageUrl)
  }
}

キャラクターモーション（Character Motion）。character-motion の選択肢は、どちらの詳細レベルでも、任意の motion オブジェクトを持つことがあります。これは、その動きが必要とするものと残すものを示します。requires、開始と終了のポーズである startPose と endPose、endVisibility、handsAfter、needsFreeHands、kind、fixedPace、counterpart、検索用の aliases、そして replacementId を伴う deprecated です。フィールドがない場合は、不明を意味します。保存されたワークフローを読み込むときは、廃止された ID も動作するようにし、新しい選択肢には表示しないでください。キャラクターモーションを参照してください。

pickerCatalogs.analyzeText(params)

自由記述のシーンの説明から、ピッカーの選択を埋めます（POST /v1/text-to-picker）。説明をピッカーへ（Describe to Picker）のテキスト版です。ピッカーのタイプ、次元、選ばれた 1 つまたは複数の id の順にキーが付いた pickerJson を返します。ピッカーには、これをそのまま読み込んでから、ユーザーに調整させてください。クレジットがかかり、説明をピッカーへと同じ課金です。

analyzeText(params: TextToPickerParams): Promise<{
  jobId: string
  pickerJson: Record<string, Record<string, string | string[]>>
  gaps?: { missingItems: object[]; missingCategories: object[] }
}>

const { pickerJson, gaps } = await client.pickerCatalogs.analyzeText({
  text: "Neon-soaked Tokyo alley at night, rain, handheld tracking shot, moody synthwave",
})
console.log(pickerJson["setting"], pickerJson["camera-motion"])

テキストが何も述べていない次元は省かれます。分析が推測することはありません。gaps は、テキストが説明している内容のうち、どのカタログの選択肢もうまく表せなかったものを、missingItems と missingCategories に一覧にします。ユーザーには「X は一致させられませんでした。自分で選んでください」のように表示します。

client.catalogs

catalogs.list(opts?)

すべてのピッカーカタログを、このデプロイメントが提供するとおりに、1 回の呼び出しで返します（GET /v1/catalogs）。デプロイメントは、選択肢を置き換え、拡張、非表示にするカタログパックを登録できます。自分でピッカーを描画するクライアントは、それらを反映させるため、この一覧を読み取ってください。これは公開されていて、5 分間キャッシュできます。

list(opts?: { detail?: "compact" | "full" }): Promise<{
  curated: boolean
  packs: number
  version: number
  data?: ProjectedCatalog[]
}>

const { curated, data } = await client.catalogs.list({ detail: "full" })
if (curated) {
  const setting = data?.find((c) => c.catalogId === "setting")
  console.log(setting?.options?.[0]?.term)
}

data が含まれるのは、デプロイメントがカタログパックを登録している場合だけです（curated: true）。パックがない場合、カタログは標準のものです。pickerCatalogs.get() で 1 つずつ読み取ってください。選択肢は同じ imageUrl を持ち、person と styling は同じ sections を持ちます。

client.presets

自分の保存したノードプリセットと、標準のノードプリセットを、読み取り専用で扱います。プリセットの data は、ノードの保存された設定です。プリセットを適用するには、ワークフローを構築するときに、その data をノードの data にマージします。OAuth トークンには presets:read スコープが必要です。プリセットを参照してください。

presets.list(nodeType?)

自分の保存したプリセットを、新しい順に一覧表示します（GET /v1/node-presets）。

list(nodeType?: string): Promise<NodePreset[]>

const presets = await client.presets.list("generate-image")
const cinematic = presets.find((p) => p.name === "Cinematic Portrait")
// apply: spread cinematic.data into the node's data when you create the workflow

NodePreset には、id、nodeType、name、description、data、groupId、tags、sortOrder、createdAt、updatedAt があります。

presets.listGroups(nodeType?)

自分のプリセットフォルダーとセクションを一覧表示します（GET /v1/node-preset-groups）。

listGroups(nodeType?: string): Promise<NodePresetGroup[]>

const groups = await client.presets.listGroups("generate-image")

各グループには、id、nodeType、name、kind（folder または section）、sortOrder、createdAt、updatedAt があります。

presets.listFactory(nodeType)

1 つのノードタイプの標準プリセットを一覧表示します（GET /v1/node-presets/factory）。

listFactory(nodeType: string): Promise<{ data: FactoryPreset[] }>

const { data } = await client.presets.listFactory("generate-video")
const orbit = data.find((p) => p.id === "generate-video/orbit-360")

client.promptHelper

プロンプトウィザードです。生成ノード用のプロンプトを書く、AI による支援です。3 つのメソッドはすべて、そのリクエストを POST /v1/prompt-helper/wizard に送信し、呼び出しごとにクレジットがかかります。REST 版については、プロンプトウィザードを参照してください。

3 つのメソッドはすべて、次の共通フィールドを受け取ります。

CLI でも、nodaro prompt wizard、analyze、generate、enhance から、--llm-model と --reasoning-effort を使って同じことができます。CLI を参照してください。

promptHelper.analyze(input)

ざっくりしたアイデアを、そのノードタイプ向けのガイド付きの質問に変えます。回答してから、その答えを generate() に渡してください。

analyze(input: AnalyzeInput): Promise<{ jobId: string; questions: WizardQuestion[] }>

const { questions } = await client.promptHelper.analyze({
  nodeType: "generate-image",
  prompt: "a snow leopard",
})

promptHelper.generate(input)

選んだ答えから、最適化された 1 つのプロンプトを作ります。各選択は { category, value, isCustom } です。

generate(input: GenerateInput): Promise<{ jobId: string; prompt: string; recommendedModel?: RecommendedModel }>

const { prompt, recommendedModel } = await client.promptHelper.generate({
  nodeType: "generate-image",
  selections: [{ category: "subject", value: "snow leopard", isCustom: false }],
})

promptHelper.enhance(input)

質問を飛ばして、プロンプトを 1 段階で改善します。

enhance(input: EnhanceInput): Promise<{ jobId: string; prompt: string; recommendedModel?: RecommendedModel }>

const { prompt } = await client.promptHelper.enhance({
  nodeType: "generate-image",
  prompt: "snow leopard on a rock",
  reasoningEffort: "high",
})