Personagens
Crie, pesquise e treine personagens, gere candidatos a retrato, aprove um deles e adicione expressões, poses e clipes de movimento com client.characters.
client.characters automatiza por script tudo o que o Estúdio de personagens faz: cria e edita personagens, gera candidatos a retrato, aprova um deles como o rosto do personagem e adiciona expressões, poses, iluminação, ângulos e clipes de movimento. Um personagem guarda o retrato, as coleções de mídias, as fotos de referência e uma legenda que o descreve, para que todas as imagens e vídeos seguintes mostrem a mesma pessoa. Os métodos chamam a API REST de personagens. Veja Estúdio de personagens para a visão do editor.
Métodos
| Método | O que faz |
|---|---|
list(params?) | Lista os seus personagens, uma página por vez |
get(id) | Lê um personagem, com as tarefas dele em andamento |
create(input), update(id, input) e upsert(input) | Cria ou altera um personagem |
delete(id) | Arquiva um personagem |
restore(id) | Traz de volta um personagem arquivado |
duplicate(id, input?) | Copia um personagem |
usage(id) | Conta os workflows que usam um personagem |
generate(input) | Gera candidatos a retrato |
generateAsset(input) | Gera uma variação de expressão, pose, iluminação ou ângulo |
generateMotion(input) | Anima o retrato em um clipe de movimento |
approvePortrait(id, candidateJobId) | Torna um candidato o retrato do personagem |
recaption(id) | Escreve de novo a descrição do personagem |
train(id, input?) | Treina um modelo de alta fidelidade do personagem, no Nodaro Cloud |
trainingStatus(id) | Lê em que pé está o treinamento do personagem |
deleteLora(id) | Remove o modelo treinado do personagem |
Criar um personagem do início ao fim
A ordem habitual: crie o personagem, gere candidatos a retrato, aprove um deles e depois adicione variações a partir dele.
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",
})Leia o personagem de novo com get() quando as tarefas terminarem. Ele terá então um retrato, uma expressão de sorriso e um clipe de movimento. Conecte-o às gerações com o nó Personagem ou mencione-o com @ em um prompt. Veja Personagens consistentes.
client.characters
list(params?)
Lista os seus personagens, dos mais recentes para os mais antigos. Por padrão, retorna apenas os personagens ativos.
list(params?: { projectId?: string; archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
characters: Character[]
nextCursor: string | null
}>Propriedade
Tipo
Uma chamada retorna no máximo limit personagens, então uma única chamada não traz a lista completa para todo mundo. Pagine até nextCursor ser 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)Passe nextCursor de volta como está, sem armazená-lo nem interpretá-lo. Um cursor malformado falha com validation_error em vez de recomeçar da primeira página.
Busca por palavras. q mantém só os personagens cujo nome ou descrição contém todas as palavras dele, em qualquer ordem, sem diferenciar maiúsculas de minúsculas. As palavras são separadas por espaços, e só as 5 primeiras contam, então "red car" encontra “Car, red”. Cada caractere de uma palavra corresponde a si mesmo: %, _ e * não são curingas. Um q em branco não faz busca, e q é limitado a 200 caracteres. Ele se combina com os outros filtros e com a paginação, então envie o mesmo q com cada cursor.
const { characters } = await client.characters.list({ q: "maya pilot", limit: 20 })get(id)
Lê um personagem, com três listas extras que o estúdio usa depois de recarregar: pendingJobs (variações ainda em geração), portraitCandidates (os candidatos da execução de retrato atual, com o progresso deles) e previousCandidates (candidatos anteriores). Ele também traz o estado do personagem na prateleira do Nodaro Keepers, catalog, catalogSort e catalogCategory, que são false, 0 e null nas suas próprias linhas e em toda cópia.
get(id: string, options?: { candidates?: "alternates" | "all" }): Promise<CharacterDetail>Propriedade
Tipo
const character = await client.characters.get(characterId)
console.log(character.sourceImageUrl, character.expressions, character.motions)Um personagem arquivado continua sendo retornado pelo ID, então os nós de workflow que apontam para ele continuam carregando. Um Character tem o retrato em sourceImageUrl, seis coleções de mídias (expressions, poses, motions, angles, bodyAngles e lightingVariations, cada uma uma lista de { name, url }), boards, voice, personality, canonicalDescription e identityLock.
upsert(input), create(input) e update(id, input)
upsert() cria um personagem quando input.id está ausente e o atualiza quando id está definido. create() e update() são atalhos que definem id por você. Uma atualização grava apenas os campos que você envia; os outros, incluindo name, continuam como estão.
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 }>Propriedade
Tipo
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" })Um nome que já está em uso falha com 409 name_taken.
delete(id)
Arquiva um personagem. Ele some de list(), mas continua carregando com get(id). Use restore() para trazê-lo de volta.
delete(id: string): Promise<{ success: true; archived: true }>Propriedade
Tipo
await client.characters.delete(characterId)restore(id)
Traz de volta um personagem arquivado. Quando o nome dele já é usado por outro personagem ativo, o servidor acrescenta (restored) ao nome e retorna o nome que usou.
restore(id: string): Promise<{ id: string; name: string }>Propriedade
Tipo
const { name } = await client.characters.restore(characterId)duplicate(id, input?)
Copia um personagem para um novo, cujo nome termina em (copy). A cópia compartilha as URLs de mídias do original até você gerar novas.
duplicate(id: string, input?: { nodeId?: string; projectId?: string }): Promise<{ id: string; name: string }>Propriedade
Tipo
const { id: copyId, name } = await client.characters.duplicate(characterId)usage(id)
Retorna quantos workflows usam um personagem, e quais. O editor mostra essa informação antes de arquivar.
usage(id: string): Promise<{ workflowCount: number; workflows: Array<{ id: string; name: string }> }>Propriedade
Tipo
const { workflowCount } = await client.characters.usage(characterId)generate(input)
Gera candidatos a retrato (POST /v1/generate-character). Com count acima de 1, todas as tarefas são reservadas antes que qualquer uma comece, então uma falha no meio do caminho desfaz o lote inteiro.
generate(input: GenerateCharacterInput): Promise<{ jobId: string; jobIds: string[] }>Propriedade
Tipo
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
})Com attachToCharacterId, cada candidato que termina é gravado no retrato, então o último a terminar prevalece. Com um único candidato, o resultado vira o retrato quando a tarefa termina. Com vários candidatos, escolha um com approvePortrait(). Passe attachPortrait: false para manter todos os candidatos fora do retrato até você aprovar um. quality e resolution são cobrados exatamente como no nó Gerar imagem, então uma execução em 4K ou em alta qualidade reserva mais créditos. Um valor da lista que o modelo não aceita não é recusado. O Nodaro usa no lugar um valor que o modelo aceita, ou descarta a configuração quando o modelo não a tem. Os créditos seguem o valor executado, e o input_data da tarefa mostra esse valor.
subject descreve quem o retrato mostra como IDs do catálogo de seletores: a idade, o cabelo e o estilo de uma pessoa, um objeto de cena na mão, um material ou um animal. O Nodaro escreve a redação e a adiciona ao prompt depois de seedPrompt, então envie os IDs em vez de escrever as palavras você mesmo. Um de seedPrompt, referencePhotos ou description continua obrigatório. Veja Descrever quem o retrato mostra.
generateAsset(input)
Gera uma variação a partir do retrato do personagem: uma expressão, uma pose, uma configuração de iluminação ou um ângulo. Com attachToCharacterId, attachToColumn e attachName, o resultado é adicionado a essa coleção do personagem quando a tarefa termina.
generateAsset(input: GenerateAssetInput): Promise<{ jobId: string }>Propriedade
Tipo
await client.characters.generateAsset({
name: "Kira",
assetType: "expressions",
variant: "smile",
attachToCharacterId: characterId,
attachToColumn: "expressions",
attachName: "smile",
})generateMotion(input)
Anima o retrato do personagem em um clipe de movimento, com o Gerar vídeo no modo imagem para vídeo. Com attachToCharacterId, o clipe é adicionado a motions do personagem. Sem sourceImageUrl, é usado o retrato do personagem.
generateMotion(input: GenerateMotionInput): Promise<{ jobId: string }>Propriedade
Tipo
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)
Torna um candidato concluído de generate() o retrato do personagem. Em seguida, um modelo de visão escreve a descrição do personagem, e o método retorna os dois.
approvePortrait(id: string, candidateJobId: string): Promise<{ portraitUrl: string; canonicalDescription: string | null }>Propriedade
Tipo
const { portraitUrl, canonicalDescription } = await client.characters.approvePortrait(characterId, jobIds[0])canonicalDescription é null quando não foi possível escrever a descrição. O retrato é definido mesmo assim; chame recaption() para tentar de novo.
recaption(id)
Escreve de novo a descrição do personagem a partir do retrato atual.
recaption(id: string): Promise<{ canonicalDescription: string }>Propriedade
Tipo
const { canonicalDescription } = await client.characters.recaption(characterId)Falha com 400 no_portrait quando o personagem não tem retrato, e com um 502 quando o modelo de visão falha.
Treinamento de personagem
Só no Nodaro Cloud. Nas outras edições essas rotas não existem, e cada chamada lança NotFoundError. Um treinamento cria um modelo de alta fidelidade do personagem a partir das imagens dele. Um nó Gerar imagem cujo prompt menciona esse único personagem com @ passa então a usar o modelo treinado. Veja Treinamento de personagem para a visão do editor.
Um treinamento reserva 1.650 créditos quando começa, leva cerca de 15 minutos e é reembolsado se falhar ou for cancelado. Com um token de app OAuth, train() e deleteLora() precisam do escopo assets:write e lançam ForbiddenError sem ele. trainingStatus() não precisa de escopo. Uma sessão do navegador ou um token de API pessoal não precisa de escopo.
train(id, input?)
Inicia um treinamento e resolve na hora com { jobId, trainingId, triggerWord }.
train(id: string, input?: { selectedImageUrls?: string[] }): Promise<TrainCharacterResult>Propriedade
Tipo
Por padrão, treina com todas as imagens elegíveis: o retrato, as fotos de referência, as expressões, as poses, os ângulos da cabeça e do corpo e as variações de iluminação. As duplicatas são removidas, e no máximo 20 imagens são usadas. Pelo menos 4 imagens distintas precisam sobrar. O método permite 3 chamadas por minuto. Treinar de novo um personagem já treinado custa o preço inteiro outra vez.
Além dos erros tipados, como ForbiddenError, InsufficientCreditsError, RateLimitedError e JobBlockedError, uma recusa é um NodaroError com um destes códigos:
code | Status | Significado |
|---|---|---|
insufficient_training_images | 400 | Menos de 4 imagens distintas. message diz quantas existem. |
validation_error | 400 | Um id ou um selectedImageUrls malformado. |
already_training_or_not_found | 409 | Um treinamento deste personagem está em andamento, ou o personagem não é seu, ou está arquivado. |
claim_failed | 500 | Não foi possível reivindicar o treinamento, e nada começou. Tente de novo. |
training_dispatch_failed | 502 | O treinamento não pôde começar, e a reserva é reembolsada. Depois disso, o status fica untrained. |
public_url_not_configured, price_not_configured | 503 | A implantação não está configurada para treinamento. |
dedup_race_winner_unresolvable | 503 | Uma duplicata desta requisição estava em andamento e não foi possível ler o resultado dela. Esta chamada não reservou nada. Leia trainingStatus() antes de tentar de novo. |
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)
Lê em que pé está o treinamento do personagem.
trainingStatus(id: string): Promise<CharacterTrainingStatus>| Campo | Descrição |
|---|---|
status | untrained, queued, training, succeeded, failed ou cancelled. untrained significa nunca treinado, modelo removido ou um treinamento que não pôde começar. |
trainingId | O treinamento mais recente. |
error | Por que um treinamento falhou. |
trainedAt, version | O último treinamento bem-sucedido. Continuam preenchidos durante um novo treinamento, depois de um que falhou ou foi cancelado, ou de um que não pôde começar. |
triggerWord | A palavra que o Nodaro adiciona aos prompts por você. |
imageCount | Quantas imagens o treinamento mais recente usou. |
A geração usa o modelo treinado só enquanto status for succeeded. O método lança NotFoundError para um personagem que não é seu ou está arquivado.
Não há função auxiliar de espera. Consulte periodicamente, a cada 10 segundos mais ou menos, enquanto o status for queued ou training. A tarefa do treinamento, o jobId de train(), também termina como completed, failed ou cancelled, então você pode acompanhar client.jobs.getStatus(jobId) no lugar.
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)
Remove o modelo treinado do personagem. Cancela um treinamento em andamento e reembolsa a reserva dele, exclui o modelo e limpa o registro. Depois disso, trainingStatus() fica untrained, e as gerações voltam a usar as imagens de referência. Não pode ser desfeito: um novo modelo é um novo treinamento, pago.
deleteLora(id: string): Promise<void>Lança ForbiddenError para um token de app OAuth sem assets:write, e NotFoundError para um personagem que não é seu ou está arquivado.
Perguntas frequentes
Como criar um personagem com o SDK do Nodaro?
Chame client.characters.create com um nodeId e um name, depois client.characters.generate para obter candidatos a retrato e client.characters.approvePortrait para escolher um. A partir daí, o personagem pode ser usado em qualquer geração de imagem ou vídeo.
Gerar o retrato de um personagem custa créditos?
Sim. Um retrato custa o mesmo que uma execução do nó Gerar imagem no modelo escolhido. quality e resolution mudam o preço; por exemplo, uma execução em 4K ou em alta qualidade custa mais.
O que acontece quando eu excluo um personagem?
delete arquiva o personagem. Ele some de list(), mas continua carregando pelo ID, então os workflows que o usam continuam funcionando. restore o traz de volta.
Como treino um personagem pelo SDK?
Chame client.characters.train(id) no Nodaro Cloud e depois consulte client.characters.trainingStatus(id) periodicamente até o status não ser mais queued nem training. Um treinamento custa 1.650 créditos, leva cerca de 15 minutos e é reembolsado se falhar.
O que identityLock faz?
Define com que intensidade o rosto é preservado quando o Nodaro gera as expressões, poses e outras variações do personagem: off, soft ou strict. O padrão é off.
Páginas relacionadas
Estúdio de personagens
Personagens consistentes
Personagem
Personagens
Treinamento de personagens
Última atualização
Cenas 3D
Em TypeScript, gere uma cena 3D editável com um prompt, edite-a, renderize-a em MP4 e execute a Renderização 3D Pro com client.scene3d e os nós de cena 3D.
Locais
Crie locais, gere planos de estabelecimento, aprove um deles e adicione variações de hora do dia, clima, estação, ângulo e movimento em TypeScript.