キャラクター
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_images | 400 | 重複のない画像が 4 枚未満です。message に、何枚あるかが示されます。 |
validation_error | 400 | ID または selectedImageUrls の形式が正しくありません。 |
already_training_or_not_found | 409 | このキャラクターの学習が実行中か、キャラクターが自分のものでないか、アーカイブされています。 |
claim_failed | 500 | 学習を確保できず、何も開始されていません。再試行してください。 |
training_dispatch_failed | 502 | 学習を開始できず、確保したクレジットは返還されます。その後の状態は untrained になります。 |
public_url_not_configured、price_not_configured | 503 | デプロイメントが学習用に設定されていません。 |
dedup_race_winner_unresolvable | 503 | このリクエストの重複が実行中で、その結果を読み取れませんでした。この呼び出しでは何も確保されていません。再試行する前に 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>| フィールド | 説明 |
|---|---|
status | untrained、queued、training、succeeded、failed、cancelled のいずれかです。untrained は、一度も学習していない、モデルが削除された、または学習を開始できなかったことを意味します。 |
trainingId | 最新の学習です。 |
error | 学習が失敗した理由です。 |
trainedAt、version | 最後に成功した学習です。新しい学習の間も、学習が失敗またはキャンセルされた場合も、学習を開始できなかった場合も、値は残ります。 |
triggerWord | Nodaro がプロンプトに自動で追加する語です。 |
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 です。
関連ページ
キャラクタースタジオ
キャラクターの一貫性
キャラクターアセット
キャラクター
キャラクター学習
最終更新