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

キャラクター

client.characters を使って、キャラクターを作成、検索、学習し、ポートレート候補を生成して 1 つを承認し、表情、ポーズ、モーションクリップを追加します。

client.characters は、キャラクタースタジオが行うことをすべてスクリプトで再現します。キャラクターの作成と編集、ポートレート候補の生成、候補の 1 つをキャラクターの顔として承認すること、そして表情、ポーズ、ライティング、アングル、モーションクリップの追加です。キャラクターは、ポートレート、アセットのコレクション、リファレンス写真、そして人物を説明するキャプションを保持するため、以降のすべての画像と動画で同じ人物を表示できます。これらのメソッドは、キャラクター REST API を呼び出します。エディターでの操作については、キャラクタースタジオを参照してください。

メソッド

メソッド内容
list(params?)自分のキャラクターを、ページ単位で一覧表示します
get(id)1 人のキャラクターを、進行中のジョブとともに読み取ります
create(input)、update(id, input)、upsert(input)キャラクターを作成または変更します
delete(id)キャラクターをアーカイブします
restore(id)アーカイブされたキャラクターを元に戻します
duplicate(id, input?)キャラクターを複製します
usage(id)キャラクターを使うワークフローを数えます
generate(input)ポートレート候補を生成します
generateAsset(input)表情、ポーズ、ライティング、アングルのバリエーションを生成します
generateMotion(input)ポートレートをアニメーション化してモーションクリップにします
approvePortrait(id, candidateJobId)候補をキャラクターのポートレートにします
recaption(id)キャラクターの説明を書き直します
train(id, input?)Nodaro Cloud で、キャラクターの高精度なモデルを学習させます
trainingStatus(id)キャラクターの学習の状況を読み取ります
deleteLora(id)キャラクターの学習済みモデルを削除します

キャラクターを最初から最後まで作成する

通常は、キャラクターを作成し、ポートレート候補を生成し、その 1 つを承認してから、その上にバリエーションを追加していきます。

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

async function waitForJob(jobId: string) {
  for (;;) {
    const { data } = await client.jobs.getStatus(jobId)
    if (data.status === "completed" || data.status === "failed" || data.status === "cancelled") return data
    await new Promise((resolve) => setTimeout(resolve, 3_000))
  }
}

// 1. Create the character
const { id: characterId } = await client.characters.create({
  nodeId: "scripted",
  name: "Kira",
  description: "Young protagonist with auburn hair",
  style: "realistic",
  seedPrompt: "Kira portrait, warm natural lighting",
})

// 2. Generate 4 portrait candidates
const { jobIds } = await client.characters.generate({
  name: "Kira",
  seedPrompt: "Kira portrait, warm natural lighting",
  count: 4,
  attachToCharacterId: characterId,
})
const results = await Promise.all(jobIds.map(waitForJob))
const firstDone = jobIds[results.findIndex((r) => r.status === "completed")]

// 3. Approve one candidate as the portrait
const { portraitUrl, canonicalDescription } = await client.characters.approvePortrait(characterId, firstDone)

// 4. Add a smile
await client.characters.generateAsset({
  name: "Kira",
  assetType: "expressions",
  variant: "smile",
  attachToCharacterId: characterId,
  attachToColumn: "expressions",
  attachName: "smile",
})

// 5. Animate the portrait
await client.characters.generateMotion({
  name: "Kira",
  motionPrompt: "Slow head turn to the left, soft smile",
  provider: "kling",
  attachToCharacterId: characterId,
  attachName: "head turn",
})

ジョブが完了したら、get() でキャラクターをもう一度読み取ります。ポートレート、smile の表情、モーションクリップが揃っています。生成先にはキャラクターアセットノードを接続するか、プロンプトで @ を使ってメンションします。キャラクターの一貫性を参照してください。

client.characters

list(params?)

自分のキャラクターを、新しい順に一覧表示します。デフォルトでは、有効なキャラクターだけを返します。

list(params?: { projectId?: string; archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
  characters: Character[]
  nextCursor: string | null
}>

プロパティ

型

1 回の呼び出しで返るのは最大 limit 件のキャラクターまでなので、1 回の呼び出しで、すべてのキャラクターが返るとは限りません。nextCursor が null になるまでページを取得してください。

import type { Character } from "@nodaro/sdk"

const all: Character[] = []
let cursor: string | undefined
do {
  const page = await client.characters.list({ projectId, cursor })
  all.push(...page.characters)
  cursor = page.nextCursor ?? undefined
} while (cursor)

nextCursor は、そのままの形で渡してください。保存したり解析したりしないでください。不正な形式のカーソルは、最初のページからやり直すのではなく、validation_error で失敗します。

語で検索する。 q は、名前または説明に q のすべての語を含むキャラクターだけを残します。語の順序と大文字・小文字は問いません。語はスペースで区切られ、最初の 5 語だけが使われるので、"red car" で「Car, red」が見つかります。語の各文字はその文字自体にだけ一致し、%、_、* はワイルドカードになりません。空白だけの q は検索なしと同じで、q は最大 200 文字です。ほかのフィルターやページングと組み合わせられるので、各 cursor と一緒に同じ q を送ってください。

const { characters } = await client.characters.list({ q: "maya pilot", limit: 20 })

get(id)

1 人のキャラクターを、スタジオが再読み込み後に使う 3 つの追加の一覧とともに読み取ります。pendingJobs(まだ生成中のバリエーション)、portraitCandidates(現在のポートレート生成の候補と、その進行状況)、previousCandidates(それより前の候補)です。キャラクターの Nodaro Keepers の棚での状態として、catalog、catalogSort、catalogCategory も含まれます。自分の行と、すべてのコピーでは false、0、null です。

get(id: string, options?: { candidates?: "alternates" | "all" }): Promise<CharacterDetail>

プロパティ

型

const character = await client.characters.get(characterId)
console.log(character.sourceImageUrl, character.expressions, character.motions)

アーカイブされたキャラクターも、ID を指定すれば引き続き返されるため、それを参照するワークフローのノードは読み込み続けられます。Character は、sourceImageUrl にポートレートを持ち、6 つのアセットコレクション(expressions、poses、motions、angles、bodyAngles、lightingVariations。いずれも { name, url } のリストです)、boards、voice、personality、canonicalDescription、identityLock を持ちます。

upsert(input)、create(input)、update(id, input)

upsert() は、input.id がない場合はキャラクターを作成し、id が設定されている場合は更新します。create() と update() は、id を自動的に設定するショートカットです。更新では、送信したフィールドだけが書き込まれます。name を含む、それ以外のフィールドはそのまま残ります。

upsert(input: UpsertCharacterInput): Promise<{ id: string; name?: string }>
create(input: Omit<UpsertCharacterInput, "id"> & { name: string }): Promise<{ id: string; name?: string }>
update(id: string, input: Omit<UpsertCharacterInput, "id">): Promise<{ id: string; name?: string }>

プロパティ

型

const { id } = await client.characters.create({
  nodeId: "scripted",
  name: "Kira",
  description: "Young protagonist with auburn hair",
  style: "realistic",
  identityLock: "strict",
})

await client.characters.update(id, { baseOutfit: "Green raincoat and boots" })

すでに使われている名前は、409 name_taken で失敗します。

delete(id)

キャラクターをアーカイブします。list() には表示されなくなりますが、get(id) では引き続き読み込めます。元に戻すには restore() を使います。

delete(id: string): Promise<{ success: true; archived: true }>

プロパティ

型

await client.characters.delete(characterId)

restore(id)

アーカイブされたキャラクターを元に戻します。その名前がすでにほかの有効なキャラクターに使われている場合、サーバーは名前に (restored) を追加し、実際に使った名前を返します。

restore(id: string): Promise<{ id: string; name: string }>

プロパティ

型

const { name } = await client.characters.restore(characterId)

duplicate(id, input?)

キャラクターを、名前が (copy) で終わる新しいキャラクターとしてコピーします。コピーは、新しいものを生成するまで、元のアセットの URL を共有します。

duplicate(id: string, input?: { nodeId?: string; projectId?: string }): Promise<{ id: string; name: string }>

プロパティ

型

const { id: copyId, name } = await client.characters.duplicate(characterId)

usage(id)

キャラクターを使っているワークフローの数と、その内訳を返します。エディターは、アーカイブする前にこれを表示します。

usage(id: string): Promise<{ workflowCount: number; workflows: Array<{ id: string; name: string }> }>

プロパティ

型

const { workflowCount } = await client.characters.usage(characterId)

generate(input)

ポートレート候補を生成します(POST /v1/generate-character)。count が 1 を超える場合、どのジョブを開始するよりも前に、すべてのジョブの分が確保されるため、途中で失敗すると、バッチ全体がロールバックされます。

generate(input: GenerateCharacterInput): Promise<{ jobId: string; jobIds: string[] }>

プロパティ

型

const { jobIds } = await client.characters.generate({
  name: "Kira",
  seedPrompt: "Kira portrait, warm natural lighting",
  subject: { type: "woman", age: "age-30s", hairBase: "base-short-straight" },
  count: 4,
  attachToCharacterId: characterId,
  provider: "gpt-image",
  quality: "high", // priced as gpt-image:high
})

attachToCharacterId を指定すると、完了した候補はすべてポートレートに書き込まれるため、最後に完了した候補が残ります。候補が 1 つの場合、ジョブが完了すると、その結果がそのままポートレートになります。候補が複数の場合は、approvePortrait() で 1 つを選びます。どれかを承認するまで、どの候補もポートレートにしないようにするには、attachPortrait: false を渡します。quality と resolution は、画像生成とまったく同じ基準で価格が決まるため、4K や高品質での実行では、より多くのクレジットが確保されます。一覧にある値のうち、モデルが対応していないものも拒否されません。Nodaro は代わりにモデルが対応している値を使い、モデルにその設定がない場合は設定を外します。クレジットは実際に使われた値に従い、その値はジョブの input_data で確認できます。

subject は、ポートレートに誰が写るかを、ピッカーのカタログの ID で指定します。人物の年齢、髪型とスタイリング、手に持つ小道具、素材、動物です。Nodaro が文言を書き、seedPrompt の後でプロンプトに追加するので、自分で文言を書く代わりに ID を送ってください。seedPrompt、referencePhotos、description のいずれかは、引き続き必要です。ポートレートに写る人物を指定するを参照してください。

generateAsset(input)

キャラクターのポートレートから、表情、ポーズ、ライティング、アングルのいずれか 1 つのバリエーションを生成します。attachToCharacterId、attachToColumn、attachName を指定すると、ジョブが完了したときに、結果がキャラクターの該当するコレクションに追加されます。

generateAsset(input: GenerateAssetInput): Promise<{ jobId: string }>

プロパティ

型

await client.characters.generateAsset({
  name: "Kira",
  assetType: "expressions",
  variant: "smile",
  attachToCharacterId: characterId,
  attachToColumn: "expressions",
  attachName: "smile",
})

generateMotion(input)

動画生成を画像から動画のモードで使い、キャラクターのポートレートをモーションクリップにアニメーション化します。attachToCharacterId を指定すると、クリップはキャラクターの motions に追加されます。sourceImageUrl を指定しない場合は、キャラクターのポートレートが使われます。

generateMotion(input: GenerateMotionInput): Promise<{ jobId: string }>

プロパティ

型

await client.characters.generateMotion({
  name: "Kira",
  motionPrompt: "Slow head turn to the left, soft smile",
  provider: "kling",
  attachToCharacterId: characterId,
  attachName: "head turn",
})

approvePortrait(id, candidateJobId)

generate() で完了した候補を、キャラクターのポートレートにします。その後、ビジョンモデルがキャラクターの説明を書き、このメソッドは両方を返します。

approvePortrait(id: string, candidateJobId: string): Promise<{ portraitUrl: string; canonicalDescription: string | null }>

プロパティ

型

const { portraitUrl, canonicalDescription } = await client.characters.approvePortrait(characterId, jobIds[0])

説明を書けなかった場合、canonicalDescription は null になります。それでもポートレートは設定されます。もう一度試すには、recaption() を呼び出してください。

recaption(id)

現在のポートレートから、キャラクターの説明を書き直します。

recaption(id: string): Promise<{ canonicalDescription: string }>

プロパティ

型

const { canonicalDescription } = await client.characters.recaption(characterId)

キャラクターにポートレートがない場合は 400 no_portrait で、ビジョンモデルが失敗した場合は 502 で失敗します。

キャラクターの学習

Nodaro Cloud 限定です。 ほかのエディションにはこれらのルートがなく、どの呼び出しも NotFoundError をスローします。学習では、キャラクター自身の画像から、そのキャラクターの高精度なモデルを作成します。そのあと、プロンプトでその 1 人のキャラクターに @ で言及した画像生成ノードは、学習済みのモデルで実行されます。エディターでの操作については、キャラクターの学習を参照してください。

学習は、開始時に 1,650 クレジットを確保し、約 15 分かかります。失敗またはキャンセルされた場合は、クレジットが返還されます。OAuth アプリのトークンでは、train() と deleteLora() に assets:write スコープが必要で、ない場合は ForbiddenError をスローします。trainingStatus() にはスコープは不要です。ブラウザーセッションや個人の API トークンには、スコープは必要ありません。

train(id, input?)

学習を開始し、すぐに { jobId, trainingId, triggerWord } で解決されます。

train(id: string, input?: { selectedImageUrls?: string[] }): Promise<TrainCharacterResult>

プロパティ

型

デフォルトでは、対象となるすべての画像で学習します。ポートレート、リファレンス写真、表情、ポーズ、頭と体のアングル、ライティングのバリエーションです。重複は取り除かれ、使われる画像は最大 20 枚です。重複のない画像が 4 枚以上残る必要があります。このメソッドは 1 分あたり 3 回まで呼び出せます。学習済みのキャラクターをもう一度学習させると、再び全額がかかります。

ForbiddenError、InsufficientCreditsError、RateLimitedError、JobBlockedError などの型付きのエラーのほかに、拒否は次のいずれかのコードを持つ NodaroError になります。

codeステータス意味
insufficient_training_images400重複のない画像が 4 枚未満です。message に、何枚あるかが示されます。
validation_error400ID または selectedImageUrls の形式が正しくありません。
already_training_or_not_found409このキャラクターの学習が実行中か、キャラクターが自分のものでないか、アーカイブされています。
claim_failed500学習を確保できず、何も開始されていません。再試行してください。
training_dispatch_failed502学習を開始できず、確保したクレジットは返還されます。その後の状態は untrained になります。
public_url_not_configured、price_not_configured503デプロイメントが学習用に設定されていません。
dedup_race_winner_unresolvable503このリクエストの重複が実行中で、その結果を読み取れませんでした。この呼び出しでは何も確保されていません。再試行する前に trainingStatus() を読み取ってください。
import { NodaroError } from "@nodaro/sdk"

try {
  const { jobId, triggerWord } = await client.characters.train(characterId)
} catch (err) {
  if (err instanceof NodaroError && err.code === "insufficient_training_images") {
    // err.message: "Need at least 4 reference photos to train (have 2). …"
  } else throw err
}

trainingStatus(id)

キャラクターの学習の状況を読み取ります。

trainingStatus(id: string): Promise<CharacterTrainingStatus>
フィールド説明
statusuntrained、queued、training、succeeded、failed、cancelled のいずれかです。untrained は、一度も学習していない、モデルが削除された、または学習を開始できなかったことを意味します。
trainingId最新の学習です。
error学習が失敗した理由です。
trainedAt、version最後に成功した学習です。新しい学習の間も、学習が失敗またはキャンセルされた場合も、学習を開始できなかった場合も、値は残ります。
triggerWordNodaro がプロンプトに自動で追加する語です。
imageCount最新の学習で使われた画像の枚数です。

生成で学習済みのモデルが使われるのは、status が succeeded の間だけです。このメソッドは、自分のものでないキャラクターや、アーカイブされたキャラクターに対して NotFoundError をスローします。

待機用のヘルパーはありません。状態が queued または training の間は、約 10 秒ごとにポーリングしてください。学習のジョブ(train() が返す jobId)も completed、failed、cancelled のいずれかで終わるので、代わりに client.jobs.getStatus(jobId) を追跡することもできます。

let training = await client.characters.trainingStatus(characterId)
while (training.status === "queued" || training.status === "training") {
  await new Promise((resolve) => setTimeout(resolve, 10_000))
  training = await client.characters.trainingStatus(characterId)
}
if (training.status !== "succeeded") console.warn(training.status, training.error)

deleteLora(id)

キャラクターの学習済みモデルを削除します。実行中の学習をキャンセルして確保したクレジットを返還し、モデルを削除してレコードをクリアします。その後、trainingStatus() は untrained になり、生成はリファレンス画像を使う方法に戻ります。元に戻すことはできません。新しいモデルを作るには、新たに有料の学習が必要です。

deleteLora(id: string): Promise<void>

assets:write のない OAuth アプリのトークンでは ForbiddenError を、自分のものでないキャラクターやアーカイブされたキャラクターでは NotFoundError をスローします。

よくある質問

Nodaro SDK でキャラクターを作成するにはどうすればよいですか?

nodeId と name を指定して client.characters.create を呼び出し、次に client.characters.generate でポートレート候補を生成し、client.characters.approvePortrait で 1 つを選びます。これで、キャラクターをあらゆる画像や動画の生成で使えるようになります。

キャラクターのポートレートを生成すると、クレジットがかかりますか?

かかります。ポートレートの料金は、選んだモデルでの画像生成の実行と同じです。quality と resolution によって価格が変わり、たとえば 4K や高品質での実行は、より高くなります。

キャラクターを削除すると、どうなりますか?

delete は、キャラクターをアーカイブします。list() には表示されなくなりますが、id を指定すれば引き続き読み込めるため、それを使うワークフローは動作し続けます。restore で元に戻せます。

SDK からキャラクターを学習させるにはどうすればよいですか?

Nodaro Cloud で client.characters.train(id) を呼び出し、状態が queued または training でなくなるまで client.characters.trainingStatus(id) をポーリングします。学習には 1,650 クレジットかかり、約 15 分かかります。失敗した場合はクレジットが返還されます。

identityLock は何をしますか?

Nodaro がキャラクターの表情、ポーズなどのバリエーションを生成するときに、顔をどれだけ厳密に保持するかを設定します。off、soft、strict のいずれかで、デフォルトは off です。

最終更新

目次