# Locais

> Crie locais num assistente de IA, gere e aprove planos de estabelecimento, adicione variações de hora do dia, tempo e ângulo e anime clipes de atmosfera.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/locations

As **ferramentas de locais** permitem que um assistente crie e use os lugares da sua biblioteca: uma rua, um cômodo ou uma paisagem com aparência fixa, que continua igual em todas as tomadas. O assistente cria um local, gera e aprova o plano de estabelecimento dele, adiciona variações de hora do dia, condições do tempo, estações, ângulos e iluminação, anima clipes de atmosfera e passa as imagens como referência para outras gerações. Leia [Locais](https://nodaro.ai/docs/guides/locations) para fazer o mesmo trabalho no app.

O ciclo de vida é o mesmo das [ferramentas de personagens](https://nodaro.ai/docs/mcp/tools/characters): criar, gerar uma imagem principal, aprová-la e depois gerar variações e movimento a partir dela.

## `list_locations`
Lista os seus locais, dos mais recentes para os mais antigos, com o nome, a descrição, a imagem principal, o número de variações de cada tipo e a identidade de cada um: descrição canônica, categoria, estilo e bloqueio de estilo. Os locais arquivados ficam de fora, a menos que você os peça.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `search` | string | Parte do nome do local, sem diferenciar maiúsculas de minúsculas, com até 100 caracteres. |
| `archived` | boolean | `true` lista os locais arquivados no lugar dos outros. |

**Retorna:** os locais. Chame `get_location` para obter as URLs das imagens.

## `get_location`
Retorna um local completo: cada variação de hora do dia, tempo, ângulo, iluminação e estação e cada clipe de atmosfera, com o nome e a URL, além das fotos de referência e dos campos de identidade.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** O ID do local, de `list_locations`. |

**Retorna:** o local, incluindo `updatedAt` para `update_location`, e as gerações ainda em andamento para ele. Um erro quando o local não existe ou não é seu.

## `create_location`
Cria um local com a identidade dele. Ele ainda não tem imagem principal: gere uma em seguida com `generate_location`.

**Permissão:** `assets:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** O nome de exibição, como `Rainy Tokyo Alley`, com até 200 caracteres. |
| `description` | string | Até 2.000 caracteres. |
| `category` | string | Uma tag de categoria, como `interior`, `exterior` ou `urban`, com até 50 caracteres. |
| `style` | string | Uma tag de estilo, como `cinematic`, `documentary` ou `noir`, com até 50 caracteres. |
| `projectId`, `workflowId`, `nodeId` | string | Vínculos opcionais com um projeto, um workflow ou um nó do canvas. Normalmente omitidos. |

**Retorna:** o ID do novo local.

## `update_location`
Altera a identidade de um local. Só são gravados os campos que você informar. As variações não podem ser editadas aqui; as ferramentas de geração as adicionam.

**Permissão:** `assets:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** O ID do local. |
| `name`, `description`, `category`, `style` | string | Como em `create_location`. |
| `canonicalDescription` | string | A descrição da cena, com até 4.000 caracteres. O seu texto substitui a legenda automática. |
| `styleLock` | boolean | Quando `true`, cada geração de variação também recebe a imagem principal como referência, para manter o layout consistente. |
| `expectedUpdatedAt` | string | O `updatedAt` de `get_location`. A alteração é recusada quando o local mudou desde a sua leitura. |

**Retorna:** uma confirmação, ou um erro de conflito quando `expectedUpdatedAt` está desatualizado.

## `approve_main_image`
Transforma um resultado concluído de `generate_location` na imagem principal do local e faz um modelo de visão descrevê-la, para preencher a descrição canônica do local.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM para a descrição.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `location_id` | string | **Obrigatório.** O local. |
| `candidate_job_id` | string | **Obrigatório.** Um job concluído de `generate_location` feito por você. |

**Retorna:** a URL da imagem principal e a descrição. Quando a descrição falha, a imagem é definida mesmo assim e a descrição fica vazia; execute `recaption_location`.

## `recaption_location`
Faz o modelo de visão descrever de novo a imagem principal atual e salva a nova descrição canônica.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `location_id` | string | **Obrigatório.** O local. |

**Retorna:** a nova descrição. `400 no_source_image` quando o local não tem imagem principal.

## `generate_location`
Gera o plano de estabelecimento de um local (`kind: "main"`) ou uma variação (`kind: "asset"`).

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de imagem.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** O nome do local. |
| `kind` | string | `main` (padrão) ou `asset`. |
| `description`, `style` | string | A identidade, para uma imagem principal. |
| `category` | string | `indoor`, `outdoor`, `urban`, `nature`, `fantasy`, `sci-fi`, `historical`, `futuristic` ou `other`. |
| `model` | string | O modelo de imagem. Padrão: `nano-banana`. |
| `asset_type` | string | Para `asset`: `timeOfDay`, `weather`, `seasons`, `angles`, `lighting` ou `custom`. |
| `variant` | string | Para `asset`: por exemplo `dawn`, `noon`, `dusk` ou `night`; `rain`, `snow` ou `fog`; de `spring` a `winter`; `aerial`, `street-level` ou `wide`; `golden-hour`, `overcast` ou `neon`; ou um rótulo curto criado por você. |
| `attach_to_location_id` | string | Salva o resultado neste local e usa a imagem principal aprovada dele como origem. Sem ela, a chamada retorna `main_image_required`. |
| `attach_to_column` | string | Obrigatório com `attach_to_location_id` para uma variação `custom`: `time_of_day`, `weather`, `seasons`, `angles`, `lighting`, `atmosphere_motions`, `sheets` ou `detail_closeups`. |
| `attach_name` | string | O nome da variação salva. Padrão: a variação. |
| `source_image_url` | string | Uma imagem de origem, quando você não anexa o resultado a um local. |

**Retorna:** um ID de job. Para uma imagem principal, passe o job para `approve_main_image` quando gostar do resultado.

## `generate_location_motion`
Anima um local num clipe de atmosfera: um movimento de câmera com movimentos sutis no ambiente, como “slow dolly-in, leaves drift across frame” ou “drone fly-over, neon signs flicker”.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de vídeo.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `motion_prompt` | string | **Obrigatório.** O movimento de câmera e o movimento na cena, com até 2.000 caracteres. |
| `source_image_url` | string | **Obrigatório.** O primeiro quadro, normalmente a imagem principal aprovada do local. |
| `name` | string | **Obrigatório.** O nome do local, usado como contexto no prompt. |
| `provider` | string | `kling` (padrão), `kling-turbo`, `kling-3.0`, `wan-i2v`, `wan-2.7-i2v` ou `seedance-2`. |
| `attach_to_location_id` | string | Salva o clipe nos clipes de atmosfera do local. |
| `attach_name` | string | O nome do clipe salvo. |
| `refine_from_video_url` | string | Refina um clipe existente com um novo prompt, como vídeo para vídeo, em vez de partir da imagem. |
| `canonical_description`, `category`, `style` | string | Contexto extra para o prompt. |

**Retorna:** um ID de job. O cartão reproduz o clipe quando ele fica pronto.

## Frequently asked questions

### Como mantenho o mesmo lugar em todas as tomadas?

Crie um local, aprove um plano de estabelecimento como imagem principal dele e gere as variações a partir dessa imagem. Passe a imagem principal ou uma variação como referência em cada imagem ou vídeo que mostra o lugar.

### Que variações um local pode ter?

Hora do dia, condições do tempo, estações do ano, ângulos de câmera e iluminação, além de variações personalizadas que você mesmo nomeia. Cada uma é gerada a partir da imagem principal aprovada e salva no local.

### O que styleLock faz?

Com styleLock ativado, cada geração de variação também recebe a imagem principal como referência, o que mantém o layout do lugar consistente entre as variações.

### Como refino um clipe de atmosfera sem começar do zero?

Chame generate_location_motion de novo com refine_from_video_url definido como o clipe e um novo prompt, como a mesma tomada com chuva fraca em vez de neblina. A ferramenta executa vídeo para vídeo nesse clipe.