# Descrever para seletor

> Analise uma foto com IA e preencha os seletores Pessoa, Figurino e beleza, Enquadramento, Lente e Câmera / película com escolhas válidas do catálogo.

Source: https://nodaro.ai/pt-BR/docs/nodes/image/describe-to-picker

O nó **Descrever para seletor** (Describe to Picker) analisa uma foto e preenche os nós de seletor que você conecta a ele. Um modelo de visão observa o assunto principal e a cena. Ele retorna escolhas que existem no catálogo de cada seletor, como a idade e o cabelo da pessoa, a maquiagem, o tamanho do plano ou a lente. Uma execução preenche todos os seletores conectados.

- Found in: Image › Understand
- Output: data
- API type: `describe-to-picker`

## Quando usar
- Transforme um retrato de referência em um briefing de elenco completo: conecte [**Pessoa** (Person)](https://nodaro.ai/docs/nodes/creative-controls/person), [**Figurino e beleza** (Styling)](https://nodaro.ai/docs/nodes/creative-controls/styling) e [**Enquadramento** (Framing)](https://nodaro.ai/docs/nodes/creative-controls/framing) e, depois, conecte esses seletores ao [**Gerar imagem** (Generate Image)](https://nodaro.ai/docs/nodes/image/generate-image) ou ao [**Gerar vídeo** (Generate Video)](https://nodaro.ai/docs/nodes/video/generate-video).
- Configure um personagem recorrente, com o figurino e o visual de lente dele, a partir de uma única foto.
- Reproduza a câmera de uma imagem de referência: detecte o tamanho do plano, o ângulo, a lente e a película.

## Início rápido
### Adicionar o nó
Pressione Tab no canvas e escolha **Imagem › Interpretação › Descrever para seletor**.

### Conectar a foto
Arraste de um nó de imagem, como o [**Enviar imagem** (Upload Image)](https://nodaro.ai/docs/nodes/image/upload-image), até a entrada **Imagem**.

### Conectar os seletores a preencher
Arraste da saída **JSON do seletor** até a entrada **JSON do seletor** de cada seletor que você quer preencher. O painel de configurações lista esses seletores em **Analisando:**.

### Executar e aplicar o resultado
Clique em **Executar** no nó. Cada seletor recebe a própria parte do resultado. Por padrão, clique em **Aplicar valores injetados** em cada seletor para aplicá-la.

Workflow: Uma foto preenche os seletores Pessoa, Figurino e beleza e Enquadramento, que depois dão forma a uma nova imagem.

- Enviar imagem → Descrever para seletor (imagem)
- Descrever para seletor → Pessoa (json do seletor)
- Descrever para seletor → Figurino e beleza (json do seletor)
- Descrever para seletor → Enquadramento (json do seletor)
- Pessoa → Gerar imagem (elementos)
- Figurino e beleza → Gerar imagem (elementos)
- Enquadramento → Gerar imagem (look)

## Entradas
| Entrada | Aceita | O que faz |
| --- | --- | --- |
| **Imagem** | Nós de imagem, como Enviar imagem e Gerar imagem | A foto a analisar. Obrigatória. |

A saída **JSON do seletor** é um dado estruturado com uma parte para cada seletor conectado. Só nós de seletor conseguem lê-la: ela não se conecta a entradas de texto.

## O que ele preenche
O nó analisa exatamente os seletores conectados à saída dele, e nenhum outro. Não há uma configuração para escolher os seletores: a conexão é a escolha.

| Seletor | O que ele detecta |
| --- | --- |
| [Pessoa](https://nodaro.ai/docs/nodes/creative-controls/person) | Traços como tipo, idade, etnia, porte físico, cabelo, olhos e pele |
| [Figurino e beleza](https://nodaro.ai/docs/nodes/creative-controls/styling) | Escolhas de figurino e beleza do catálogo do seletor, como maquiagem, óculos e joias |
| [Enquadramento](https://nodaro.ai/docs/nodes/creative-controls/framing) | Tamanho do plano, ângulo e composição |
| [**Lente** (Lens)](https://nodaro.ai/docs/nodes/creative-controls/lens) | A lente |
| [**Câmera / película** (Camera / Film Stock)](https://nodaro.ai/docs/nodes/creative-controls/camera-format) | A câmera ou o formato de filme |

Cada valor é uma escolha real do catálogo do próprio seletor, então um seletor nunca recebe um valor que ele não conhece. Um traço que não está visível na foto fica de fora.

## Como os seletores aplicam o resultado
Cada seletor decide como usar a própria parte do resultado, com duas configurações no painel de configurações dele.

**Quando um JSON de imagem é injetado** escolhe como os novos valores se combinam com as escolhas atuais do seletor:

| Modo | O que faz |
| --- | --- |
| **Substituir tudo (limpar o que não foi detectado)** | O padrão. Grava todos os valores detectados e limpa todos os valores que não foram detectados. Use quando a foto deve definir o seletor por completo. |
| **Sobrescrever o detectado (manter o resto)** | Grava só os valores detectados e mantém as suas outras escolhas. |
| **Preencher só os vazios** | Grava um valor detectado só onde o campo está vazio. Nunca sobrescreve uma escolha que você fez. |

**Aplicar automaticamente ao mudar** vem desativado por padrão. Quando está desativado, o seletor mostra um botão **Aplicar valores injetados** quando um novo resultado é diferente do que ele aplicou por último. Caso contrário, ele mostra **Atualizado**. Quando está ativado, cada novo resultado é aplicado na hora, com o modo escolhido. Executar a análise de novo com o mesmo resultado não marca o seletor como alterado.

Em todos os modos, só as escolhas do seletor mudam. O rótulo do seletor, o texto antes e depois dele e o layout dele continuam como estão.

## Configurações
| Configuração | O que faz |
| --- | --- |
| **Analisando:** | Somente leitura. Os seletores conectados que a próxima execução vai preencher. Para mudar, conecte ou desconecte seletores. |
| **Modelo de IA** | O modelo de visão. O padrão é o Claude Opus 5, escolhido pela precisão em detalhes como o tom de pele. A lista oferece só modelos de visão que conseguem retornar esse resultado estruturado com confiabilidade, das famílias Claude, Gemini, GPT e Grok. |
| **Esforço de raciocínio** | Quanto o modelo raciocina antes de responder, nos modelos que oferecem essa opção. O padrão é **Automático (padrão do modelo)**. |
| **Modo avançado** | Só para modelos Gemini. Executa o modelo diretamente no provedor, para que **Temperatura**, **Máx. de tokens** e toda a faixa de profundidade de raciocínio tenham efeito. |
| **Orientações extras (opcional)** | As suas próprias instruções para a análise, com até 2.000 caracteres, por exemplo `focus on the foreground subject`. |

## Créditos
Toda execução custa 11 créditos, um valor fixo, qualquer que seja o modelo e quantos seletores você conectar. A análise inteira é uma única chamada ao modelo. Os créditos são reservados quando a execução começa e reembolsados se a análise falhar.

## Solução de problemas
**A execução é recusada com uma mensagem para conectar um nó de seletor.** Nada que o nó consiga preencher está conectado à saída dele. Conecte pelo menos um seletor Pessoa, Figurino e beleza, Enquadramento, Lente ou Câmera / película.

**Um seletor não mudou depois da execução.** **Aplicar automaticamente ao mudar** vem desativado por padrão. Clique em **Aplicar valores injetados** no seletor, ou ative **Aplicar automaticamente ao mudar**.

**O nó descreveu a pessoa errada.** Quando uma foto tem várias pessoas ou um fundo cheio de elementos, adicione **Orientações extras (opcional)**, como `describe the woman in the red coat`.

## Dicas
- **Preencha vários seletores em uma execução.** Pessoa, Figurino e beleza e Enquadramento juntos transformam uma foto em um briefing de elenco, de visual e de tomada, pelo mesmo preço de um seletor.
- **Proteja as suas escolhas.** Use **Preencher só os vazios** quando você escolheu à mão alguns traços marcantes e quer que a foto preencha o resto.
- **Atualize sem perder os extras.** Use **Sobrescrever o detectado (manter o resto)** para atualizar o que a foto mostra e manter as escolhas que você adicionou à mão.
- **Refaça do zero.** Use **Substituir tudo (limpar o que não foi detectado)** para ter uma versão limpa do seletor, guiada pela foto.

## Pela API
O `POST /v1/describe-to-picker` executa a mesma análise a partir de código. Ele responde na mesma requisição com `{ jobId, pickerJson, gaps }`. O `pickerJson` dá a cada seletor os valores detectados, como `{ "<picker>": { "<dimension>": "<id>" } }`, com uma lista de IDs onde uma dimensão aceita várias escolhas.

| Campo | O que faz |
| --- | --- |
| `imageUrl` | Obrigatório. Um link público `http` ou `https` para a foto. |
| `targetPickers` | Obrigatório. Os seletores a preencher, como `person`, `styling`, `framing`, `lens` e `camera-format`. |
| `instructions` | **Orientações extras (opcional)**, com até 2.000 caracteres. |
| `llmModel` | O modelo de visão. O padrão é `claude-opus-5`. |
| `reasoningEffort` | `none`, `low`, `medium`, `high`, `xhigh` ou `max`. |
| `advancedMode`, `temperature`, `maxTokens` | O **Modo avançado** e os controles dele, só nos modelos Gemini. |

**Transmita a resposta.** Envie `Accept: text/event-stream` para receber a resposta como eventos enviados pelo servidor, para que um cliente possa mostrar cada característica assim que o modelo a escrever. Um erro encontrado antes de o fluxo abrir, como uma requisição inválida ou créditos insuficientes, continua sendo uma resposta HTTP comum, com o corpo de erro JSON de sempre. O fluxo responde `200`, e cada evento é uma linha `data:` com um objeto JSON, `{ "type", "data" }`:

| `type` | `data` | Significado |
| --- | --- | --- |
| `field` | `{ "field": "<picker>.<dimension>", "value" }` | Uma característica detectada, enviada uma vez, assim que o modelo termina de escrevê-la. Ela é provisória: o `done` ainda pode corrigi-la. |
| `done` | `{ jobId, pickerJson, gaps }` | A mesma resposta do JSON. Ela é final. |
| `error` | `{ "code": "llm_error", "message" }` | A análise falhou depois que o fluxo abriu. Os créditos são reembolsados. |

- O fluxo termina depois de `done` ou `error`. Ignore linhas de comentário, como `: keepalive`.
- Com um modelo Claude, as características podem chegar como eventos `field`. Os outros modelos enviam só `done`.
- Um evento `field` nunca traz um valor que as [regras para pessoas com menos de 20 anos](https://nodaro.ai/docs/nodes/creative-controls/person#people-under-20) possam remover. Esses valores chegam só no `done`.
- Uma requisição é uma análise. Os créditos dela são confirmados com `done` e reembolsados com `error`. Se o cliente se desconectar, a análise termina mesmo assim e é cobrada.

Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes).

## Frequently asked questions

### Quais seletores o “Descrever para seletor” consegue preencher?

Pessoa, Figurino e beleza, Enquadramento, Lente e Câmera / película. Ele preenche exatamente os que você conecta à saída dele, em uma única análise.

### Quantos créditos o “Descrever para seletor” custa?

11 créditos por execução, um valor fixo, qualquer que seja o modelo e quantos seletores você conectar. Se a análise falhar, os créditos são reembolsados.

### Ele vai sobrescrever as escolhas que fiz à mão?

Depende da configuração “Quando um JSON de imagem é injetado” de cada seletor. “Preencher só os vazios” nunca sobrescreve as suas escolhas. “Sobrescrever o detectado” mantém tudo o que não foi detectado. “Substituir tudo”, o padrão, também limpa tudo o que não foi detectado.

### Por que nada mudou no meu seletor?

A opção “Aplicar automaticamente ao mudar” vem desativada por padrão. Clique em “Aplicar valores injetados” no seletor para aplicar os novos valores, ou ative “Aplicar automaticamente ao mudar”.

### Qual é a diferença entre o “Descrever para seletor” e o “Descrever imagem”?

O “Descrever imagem” escreve texto livre. O “Descrever para seletor” retorna escolhas estruturadas que existem no catálogo de cada seletor, para que os seletores possam aplicá-las diretamente.