# Comandos de entidades

> Crie personagens, locais e objetos pela CLI do Nodaro, gere e aprove suas imagens principais e adicione variações e clipes de movimento a cada entidade.

Source: https://nodaro.ai/pt-BR/docs/developers/cli/asset-commands

Os **comandos de entidades** da CLI do Nodaro gerenciam personagens, locais e objetos: as identidades reutilizáveis que mantêm uma pessoa, um lugar ou um adereço iguais em todas as gerações. Cada entidade tem uma imagem principal que você gera e aprova, e variações e clipes de movimento que você adiciona depois. As mesmas entidades aparecem nos nós [**Personagem** (Character Asset)](https://nodaro.ai/docs/nodes/assets/character), [**Local** (Location Asset)](https://nodaro.ai/docs/nodes/assets/location) e [**Objeto/adereço** (Object/Props Asset)](https://nodaro.ai/docs/nodes/assets/object) do editor.

## Como uma entidade é criada
### Criar o registro
`create` salva o nome, a descrição e o estilo da entidade.

### Gerar candidatos
`generate` cria 1, 2 ou 4 candidatos a imagem principal. Adicione `--watch` para aguardar por eles.

### Aprovar um candidato
`approve-portrait` (personagens) ou `approve-main-image` (locais e objetos) define a imagem principal a partir de um job de candidato concluído. Em seguida, o Nodaro escreve a descrição da entidade a partir da imagem.

### Adicionar variações e movimento
`generate-asset` adiciona uma variação, como uma expressão ou uma estação. `generate-motion` anima a imagem principal em um clipe curto.

Cada geração custa créditos, como o nó correspondente no editor. Veja [Personagens consistentes](https://nodaro.ai/docs/guides/consistent-characters) para entender como as entidades mantêm as identidades estáveis.

## Personagens
```bash
nodaro characters list [--project <id>] [--archived] [--limit <n>] [--json]
nodaro characters get <id>
nodaro characters create --name <name> [--description "..."] [--gender <gender>] [--style realistic|anime|3d-pixar|illustration] [--base-outfit "..."] [--seed-prompt "..."] [--node-id <id>] [--project <id>]
nodaro characters update <id> [--name <name>] [--description "..."] [--gender <gender>] [--style realistic|anime|3d-pixar|illustration] [--base-outfit "..."] [--seed-prompt "..."]
nodaro characters delete <id>
nodaro characters restore <id>
nodaro characters duplicate <id> [--node-id <id>] [--project <id>]
nodaro characters usage <id>
nodaro characters generate <id> [--seed-prompt "..."] [--description "..."] [--name <name>] [--count 1|2|4] [--provider <p>] [--watch]
nodaro characters generate-asset <id> --asset-type expressions|poses|lighting|angles|headAngles|bodyAngles|custom --variant <name> [--user-prompt "..."] [--description "..."] [--column <col>] [--attach-name <name>] [--provider <p>] [--watch]
nodaro characters generate-motion <id> --motion-prompt "..." [--attach-name <name>] [--description "..."] [--motion-description "..."] [--provider <p>] [--watch]
nodaro characters approve-portrait <id> --job <jobId>
nodaro characters recaption <id>
```

| Comando | O que faz |
| --- | --- |
| `list` | Lista seus personagens, ou os arquivados com `--archived`. `--project` limita a lista a um projeto. |
| `delete` | Arquiva o personagem. `restore` o traz de volta. |
| `duplicate` | Copia o personagem para um novo registro. |
| `usage` | Lista os workflows que usam o personagem. |
| `generate` | Cria 1, 2 ou 4 candidatos a retrato. |
| `approve-portrait` | Define o retrato a partir de um job de candidato concluído e depois escreve a descrição do personagem a partir dele. |
| `generate-asset` | Cria uma variação: uma expressão, uma pose, uma iluminação, um ângulo, um ângulo da cabeça, um ângulo do corpo ou uma variação personalizada. |
| `generate-motion` | Anima o retrato em um clipe de movimento. |
| `recaption` | Reescreve a descrição a partir do retrato atual. |

## Locais
```bash
nodaro locations list [--archived] [--json]
nodaro locations get <id> [--json]
nodaro locations create <name> --node-id <id> [--description "..."] [--category indoor|outdoor|urban|nature|fantasy|sci-fi|historical|futuristic|other] [--style realistic|anime|3d-pixar|illustration] [--project <id>] [--json]
nodaro locations update <id> [--name <name>] [--description "..."] [--category <category>] [--style <style>] [--style-lock true|false] [--canonical-description "..."] [--expected-updated-at <iso>] [--json]
nodaro locations delete <id> [--json]
nodaro locations restore <id> [--json]
nodaro locations generate --name <name> [--description "..."] [--user-prompt "..."] [--category <category>] [--style <style>] [--provider <p>] [--count 1|2|4] [--attach-to-location-id <id>] [--watch] [--json]
nodaro locations generate-asset <id> --asset-type timeOfDay|weather|seasons|angles|lighting|custom --variant <name> [--user-prompt "..."] [--description "..."] [--column <col>] [--attach-name <name>] [--provider <p>] [--watch] [--json]
nodaro locations generate-motion --name <name> --motion-prompt "..." --source-image-url <url> [--provider kling|kling-turbo|kling-3.0|wan-i2v|wan-2.7-i2v|seedance-2] [--style realistic|anime|3d-pixar|illustration] [--canonical-description "..."] [--attach-to-location-id <id>] [--attach-name <name>] [--aspect-ratio 1:1|3:4|16:9|9:16] [--watch] [--json]
nodaro locations approve-main-image <id> --candidate-job-id <jobId> [--json]
nodaro locations recaption <id> [--json]
```

- `generate` cria candidatos a plano de estabelecimento. Com `--attach-to-location-id` e uma contagem de 1, o resultado vira a imagem principal do local quando o job termina. Com mais candidatos, escolha um com `approve-main-image`.
- `generate-asset` cria uma variação: uma hora do dia, uma condição do tempo, uma estação, um ângulo, uma iluminação ou uma variação personalizada.
- `generate-motion` anima uma imagem de origem em um clipe, com um dos modelos de vídeo listados.
- `--style-lock` define se as gerações de variações ficam ancoradas no estilo canônico do local.
- `--expected-updated-at` impede que uma atualização sobrescreva uma alteração mais recente. Se o registro mudou depois desse horário, a atualização é recusada com `concurrent_modification`; leia o registro de novo e tente outra vez.

## Objetos
```bash
nodaro objects list [--project <id>] [--archived] [--json]
nodaro objects get <id> [--json]
nodaro objects create <name> --node-id <id> [--description "..."] [--category furniture|vehicle|weapon|food|clothing|electronics|nature|tool|animal|other] [--style realistic|anime|3d-pixar|illustration] [--project <id>] [--json]
nodaro objects update <id> [--name <name>] [--description "..."] [--category <category>] [--style <style>] [--style-lock true|false] [--canonical-description "..."] [--expected-updated-at <iso>] [--json]
nodaro objects delete <id> [--permanent] [--json]
nodaro objects restore <id> [--json]
nodaro objects generate --name <name> [--description "..."] [--user-prompt "..."] [--category <category>] [--style <style>] [--provider <p>] [--count 1|2|4] [--attach-to-object-id <id>] [--seed-prompt-hint "..."] [--watch] [--json]
nodaro objects generate-asset --asset-type angles|materials|variations|motion|custom --variant <name> --attach-to-object-id <id> [--attach-to-column <col>] [--name <name>] [--description "..."] [--seed-prompt-hint "..."] [--watch] [--json]
nodaro objects generate-motion --name <name> --motion-prompt "..." --source-image-url <url> [--provider kling-turbo|kling|kling-3.0|minimax|hailuo-2.3|wan-i2v|seedance|bytedance-lite] [--style realistic|anime|3d-pixar|illustration] [--canonical-description "..."] [--attach-to-object-id <id>] [--attach-name <name>] [--aspect-ratio 1:1|3:4|16:9|9:16|4:3] [--seed-prompt-hint "..."] [--watch] [--json]
nodaro objects approve-main-image <id> --candidate-job-id <jobId> [--expected-updated-at <iso>] [--json]
nodaro objects recaption <id> [--json]
```

- `delete` arquiva o objeto. `delete --permanent` apaga um objeto que já está arquivado. `restore` traz de volta um objeto arquivado.
- `generate` cria 1, 2 ou 4 candidatos a imagem principal. Com `--attach-to-object-id` e uma contagem de 1, o resultado vira a imagem principal do objeto quando o job termina.
- `generate-asset` cria uma variação, vinculada ao objeto que você indicar: um ângulo, um material, uma variação, um movimento ou uma variação personalizada.
- `generate-motion` anima a imagem principal do objeto em um clipe. O modelo padrão é `kling-turbo`, e a proporção padrão é `1:1`.

## Exemplo: um personagem do início ao fim
```bash
# 1. Create the character
nodaro characters create --name Kira --description "young protagonist with auburn hair" \
  --style realistic --seed-prompt "kira portrait, warm natural lighting"

# 2. Generate four portrait candidates and wait for them
nodaro characters generate <characterId> --count 4 --watch

# 3. Approve the candidate you like
nodaro characters approve-portrait <characterId> --job <candidateJobId>

# 4. Add a smiling expression
nodaro characters generate-asset <characterId> --asset-type expressions --variant smile --watch
```

## Frequently asked questions

### Como crio um personagem com retrato pela CLI?

Crie o registro com nodaro characters create, gere candidatos a retrato com nodaro characters generate e --count 4, e depois aprove o que você preferir com nodaro characters approve-portrait e o id do job do candidato.

### Um personagem excluído some para sempre?

Não. O comando delete arquiva um personagem, um local ou um objeto, e o comando restore o traz de volta. Só os objetos podem ser apagados de vez, com delete --permanent em um objeto que já está arquivado.

### O que é uma variação de uma entidade?

Uma variação é uma imagem extra da mesma entidade, como uma expressão ou uma pose de um personagem, uma hora do dia ou uma estação de um local, ou um material de um objeto. Gere uma variação com o comando generate-asset.

### O que o recaption faz?

Ele reescreve a descrição da entidade a partir da imagem principal atual. Aprovar um retrato ou uma imagem principal já faz isso, então execute recaption só quando essa descrição tiver falhado ou a imagem tiver mudado.