NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
SDK para TypeScript

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étodoO 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.

Última atualização

Nesta página