NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
SDK para TypeScript

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étodoO 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:

codeStatusSignificado
insufficient_training_images400Menos de 4 imagens distintas. message diz quantas existem.
validation_error400Um id ou um selectedImageUrls malformado.
already_training_or_not_found409Um treinamento deste personagem está em andamento, ou o personagem não é seu, ou está arquivado.
claim_failed500Não foi possível reivindicar o treinamento, e nada começou. Tente de novo.
training_dispatch_failed502O treinamento não pôde começar, e a reserva é reembolsada. Depois disso, o status fica untrained.
public_url_not_configured, price_not_configured503A implantação não está configurada para treinamento.
dedup_race_winner_unresolvable503Uma 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>
CampoDescrição
statusuntrained, queued, training, succeeded, failed ou cancelled. untrained significa nunca treinado, modelo removido ou um treinamento que não pôde começar.
trainingIdO treinamento mais recente.
errorPor que um treinamento falhou.
trainedAt, versionO ú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.
triggerWordA palavra que o Nodaro adiciona aos prompts por você.
imageCountQuantas 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.

Última atualização

Nesta página