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.
client.locations automatiza por script tudo o que o Estúdio de locais faz. Ele cria e edita locais, gera candidatos a plano de estabelecimento, aprova um deles como a imagem principal e adiciona variações de hora do dia, clima, estações, ângulos e iluminação, além de clipes de atmosfera. Um local guarda a imagem principal, as coleções de variações, as fotos de referência e uma legenda, para que todos os planos seguintes mostrem o mesmo lugar. Os métodos chamam a API REST de locais. Veja Locais para a visão do editor.
Métodos
| Método | O que faz |
|---|---|
list(params?) | Lista os seus locais |
listArchived(params?) | Lista os seus locais arquivados |
get(id) | Lê um local, com as tarefas dele em andamento |
create(input) | Cria um local |
update(id, input) | Altera um local |
delete(id) e restore(id) | Arquiva um local ou o traz de volta |
generate(input) | Gera candidatos a plano de estabelecimento |
generateAsset(input) | Gera uma variação de hora do dia, clima, estação, ângulo ou iluminação |
generateSurroundContinuation(input) | Gera a próxima vista de um anel de 360 graus |
generateMotion(input) | Anima a imagem principal em um clipe de atmosfera |
removeAsset(id, data) | Remove um take de uma coleção de variações |
approveMainImage(id, candidateJobId) | Torna um candidato a imagem principal |
recaption(id) | Escreve de novo a descrição do local |
client.locations
list(params?)
Lista os seus locais. Por padrão, retorna apenas os locais ativos. A paginação é opcional: sem limit, você recebe a lista inteira e nenhum cursor; com limit, no máximo 500, você recebe uma página e um nextCursor.
list(params?: { archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
locations: Location[]
nextCursor?: string | null
}>Propriedade
Tipo
const { locations } = await client.locations.list()
const { locations: cafes } = await client.locations.list({ q: "café" })
const page = await client.locations.list({ limit: 100 })
const next = await client.locations.list({ limit: 100, cursor: page.nextCursor ?? undefined })Continue paginando até nextCursor ser null. As regras de busca de q estão em Personagens: as 5 primeiras palavras contam, e %, _ e * não são curingas. Envie o mesmo q com cada cursor.
listArchived(params?)
Lista os seus locais arquivados. É um atalho para list({ archived: true }).
listArchived(params?: { limit?: number; cursor?: string }): Promise<{ locations: Location[]; nextCursor?: string | null }>Propriedade
Tipo
const { locations: archived } = await client.locations.listArchived()get(id)
Lê um local, com pendingJobs, as variações ainda em geração, e previousCandidates, até 5 candidatos a imagem principal de gerações anteriores, dos mais recentes para os mais antigos. Promova um deles com approveMainImage().
get(id: string): Promise<LocationDetail>Propriedade
Tipo
const location = await client.locations.get(locationId)
console.log(location.sourceImageUrl, location.weather, location.atmosphereMotions)Um local arquivado continua sendo retornado pelo ID, então os nós de workflow que apontam para ele continuam carregando. Um Location tem a imagem principal em sourceImageUrl, seis coleções (timeOfDay, weather, seasons, angles, lighting e atmosphereMotions, cada uma uma lista de { name, url }), boards, referencePhotos, canonicalDescription, styleLock e updatedAt.
create(input)
Cria um local. name e nodeId são obrigatórios. Um script sem nó no canvas pode passar "mcp-managed" como nodeId.
create(input: CreateLocationInput): Promise<{ id: string }>Propriedade
Tipo
const { id: locationId } = await client.locations.create({
nodeId: "mcp-managed",
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
category: "urban",
style: "realistic",
})update(id, input)
Altera um local. Só os campos que você envia são gravados. As coleções de variações não fazem parte desta chamada, porque as tarefas de geração as alimentam enquanto você trabalha. Use generateAsset() e removeAsset() para elas.
update(id: string, input: UpdateLocationInput): Promise<{ id: string; updatedAt: string }>Propriedade
Tipo
await client.locations.update(locationId, {
canonicalDescription: "A narrow, rain-soaked alley lit by neon signs",
styleLock: false,
piiConsentAt: new Date().toISOString(),
expectedUpdatedAt: location.updatedAt,
})O 409 concurrent_modification chega como um NodaroError simples com esse code. Leia o local de novo, mescle a sua alteração e tente outra vez.
delete(id) e restore(id)
delete() arquiva um local, e restore() o traz de volta. A exclusão permanente só está disponível no app do Nodaro. Quando o nome restaurado coincide com o nome de um local ativo, sem diferenciar maiúsculas de minúsculas, o servidor acrescenta (restored) e retorna o nome que usou.
delete(id: string): Promise<{ success: true; archived: true }>
restore(id: string): Promise<{ id: string; name: string }>Propriedade
Tipo
await client.locations.delete(locationId)
const { name } = await client.locations.restore(locationId)generate(input)
Gera candidatos a plano de estabelecimento (POST /v1/generate-location). 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.
generate(input: GenerateLocationInput): Promise<{ jobIds: string[]; jobId?: string }>Propriedade
Tipo
// One candidate, written to the location when it completes
const { jobIds: [jobId] } = await client.locations.generate({
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
attachToLocationId: locationId,
})
// Four candidates to choose from
const { jobIds } = await client.locations.generate({ name: "Rainy Tokyo Alley", count: 4 })Com attachToLocationId e count igual a 1, o resultado vira a imagem principal quando a tarefa termina. Caso contrário, escolha um candidato com approveMainImage(). quality e resolution são cobrados como no nó Gerar imagem. 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.
generateAsset(input)
Gera uma variação do local (POST /v1/generate-location-asset). Com attachToLocationId, attachToColumn e attachName, o resultado é adicionado a essa coleção quando a tarefa termina.
generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.locations.generateAsset({
name: "Rainy Tokyo Alley",
assetType: "weather",
variant: "storm",
attachToLocationId: locationId,
attachToColumn: "weather",
attachName: "storm",
})generateSurroundContinuation(input)
Gera a próxima vista de um anel de 360 graus (POST /v1/generate-surround-continuation), continuando a partir da vista anterior. O servidor mantém metade da vista anterior exatamente como está, pinta a outra metade e harmoniza as cores, para que vistas vizinhas se juntem sem emenda. Este método funciona no Nodaro Cloud; as outras edições respondem 403 edition_required antes de qualquer processamento, e o SDK lança isso como ForbiddenError.
generateSurroundContinuation(input: GenerateSurroundContinuationInput): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.locations.generateSurroundContinuation({
referenceImageUrl: previousRingView,
direction: "right",
degrees: 45,
provider: "nano-banana-pro",
aspectRatio: "16:9",
attachToLocationId: locationId,
attachToColumn: "angles",
attachName: "Surround 45°",
})generateMotion(input)
Anima a imagem do local em um clipe de atmosfera (POST /v1/generate-location-motion), com o Gerar vídeo no modo imagem para vídeo. Um local tem uma única coleção de movimento, então o clipe sempre vai para atmosphereMotions e não existe attachToColumn.
generateMotion(input: GenerateLocationMotionInput): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.locations.generateMotion({
name: "Rainy Tokyo Alley",
motionPrompt: "Slow dolly-in, neon signs flicker, light rain falling",
sourceImageUrl: location.sourceImageUrl!,
provider: "kling",
attachToLocationId: locationId,
attachName: "neon dolly-in",
})removeAsset(id, data)
Remove um take de uma coleção de variações (POST /v1/locations/:id/remove-asset). Todas as entradas com essa url são removidas de uma vez. Use-o, por exemplo, antes de gerar de novo uma vista de 360 graus.
removeAsset(id: string, data: { column: LocationAttachColumn; url: string }): Promise<{ removed: true }>Propriedade
Tipo
await client.locations.removeAsset(locationId, { column: "angles", url: oldViewUrl })Lança NotFoundError quando a URL não está nessa coleção ou o local não é seu.
approveMainImage(id, candidateJobId)
Torna um candidato concluído de generate() a imagem principal do local. Em seguida, um modelo de visão escreve a descrição do local, e o método retorna as duas.
approveMainImage(id: string, candidateJobId: string): Promise<{ sourceImageUrl: string; canonicalDescription: string | null }>Propriedade
Tipo
const { sourceImageUrl, canonicalDescription } = await client.locations.approveMainImage(locationId, jobIds[0])canonicalDescription é null quando não foi possível escrever a descrição. A imagem principal é definida mesmo assim; chame recaption() para tentar de novo.
recaption(id)
Escreve de novo a descrição do local a partir da imagem principal atual.
recaption(id: string): Promise<{ canonicalDescription: string }>Propriedade
Tipo
const { canonicalDescription } = await client.locations.recaption(locationId)Falha com 400 no_source_image quando o local não tem imagem principal, e com um 502 quando o modelo de visão falha.
Perguntas frequentes
Como criar um local com o SDK do Nodaro?
Chame client.locations.create com um nodeId e um name, gere planos de estabelecimento com client.locations.generate e aprove um deles com client.locations.approveMainImage.
Quais variações posso gerar para um local?
Hora do dia, clima, estações, ângulos e iluminação, além de variações personalizadas, com generateAsset, e clipes de atmosfera com generateMotion. No Nodaro Cloud, generateSurroundContinuation adiciona vistas de 360 graus.
Como evitar sobrescrever um local que outra pessoa alterou?
Passe expectedUpdatedAt, o valor de updatedAt que você leu, para client.locations.update. Se o local tiver mudado, a chamada falha com 409 concurrent_modification. Leia o local de novo, mescle e tente outra vez.
Posso excluir um local de forma permanente com o SDK?
Não. delete arquiva o local, e restore o traz de volta. A exclusão permanente só está disponível no app do Nodaro.
Páginas relacionadas
Locais
Local
Locais
Personagens
Objetos e criaturas
Última atualização
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.
Objetos e criaturas
Crie objetos e criaturas, gere imagens principais e variações, anime-os e faça uma criatura falar em TypeScript com o SDK do Nodaro.