Locais

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

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; limit?: number; cursor?: string }): Promise<{
  locations: Location[]
  nextCursor?: string | null
}>

const { locations } = await client.locations.list()

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.

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 }>

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>

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 }>

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 os jobs de geração as alimentam enquanto você trabalha. Use generateAsset() e removeAsset() para elas.

update(id: string, input: UpdateLocationInput): Promise<{ id: string; updatedAt: string }>

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 }>

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, todos os jobs são reservados antes que qualquer um comece, então uma falha no meio do caminho desfaz o lote.

generate(input: GenerateLocationInput): Promise<{ jobIds: string[]; jobId?: string }>

// 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 o job termina. Caso contrário, escolha um candidato com approveMainImage(). quality e resolution são cobrados como no nó Gerar imagem (Generate Image). Um valor que o modelo não aceita é ignorado.

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 o job termina.

generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>

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 }>

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 (Generate Video) 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 }>

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 }>

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 }>

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 }>

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.