Agentes de AI para Fotos de Imóveis: Um Playbook de API para 2026

A Mudança: De Modelos Que Descrevem Softwares para Agentes Que os Operam

Até recentemente, a relação de um modelo de AI com o seu software imobiliário era consultiva. Ele podia lhe dizer o que escrever no CRM. Ele não podia abrir o CRM.

Essa fronteira mudou em setembro de 2026. A OpenAI anunciou o GPT-6 Astra em 3 de setembro com a frase "Anything you can do on a computer, Astra can do for you" ("Tudo o que você pode fazer em um computador, o Astra pode fazer por você"), e relata 72,6% no benchmark de uso de computador OSWorld 2.0 a cerca de 40 minutos por tarefa, contra 65,7% em aproximadamente 75 minutos para seu antecessor, o GPT-5.6 Sol. O Astra recebe texto e imagens como entrada e retorna apenas texto. Sua API custa $ 10 por milhão de tokens de entrada e $ 50 por milhão de tokens de saída na tarifa padrão, e a OpenAI também lista o GPT-6.1 Sol a um quinto desse valor ($ 2 / $ 10). O Project Astra, do Google, com nome semelhante, é um protótipo de pesquisa separado, utilizado por um grupo restrito de avaliadores de confiança.

Para a mídia imobiliária, isso altera quem aperta os botões. Um ensaio fotográfico de anúncio sempre foi uma sequência de operações de software: fazer upload, selecionar, fazer o staging, aprimorar, converter, rotular, publicar. Todas elas agora podem ser automatizadas de ponta a ponta, o que levanta uma questão que a maioria das equipes de proptech ainda não respondeu: como a sua estrutura tecnológica precisa ser para que um agente a opere com segurança?

A resposta resumida: o agente lê, classifica e confere; uma API de imagens produz os pixels; seu código gerencia as chaves, o orçamento e as regras de divulgação; e uma pessoa aprova qualquer coisa que um comprador, inquilino ou hóspede vá ver.

O acesso ao ChatGPT, preços completos e classificações de benchmark estão em GPT-6 Astra for Real Estate. Este artigo aborda a parte de infraestrutura técnica.

Como É o Fluxo de Mídia Operado por Agentes

Uma API de processamento de fotos é o que torna isso operável: você envia uma foto e uma instrução (uma ferramenta e suas opções) via HTTPS, e recebe de volta um job que pode acompanhar até que a imagem editada esteja pronta. Ao redor disso, o ciclo para um anúncio funciona assim:

As etapas 2, 3, 6 e 8 são onde um modelo baseado em agentes mostra seu valor. A etapa 4 é onde ele passa o bastão, porque o GPT-6 Astra retorna texto, não imagens (veja Can GPT-6 Astra Do Virtual Staging or Generate Images?).

O agente deve chamar uma API, e não clicar em uma aplicação web. O uso do computador é uma camada de compatibilidade para softwares que não têm API. Quando existe uma API, utilizá-la é mais rápido, mais barato, determinístico e, a parte que importa às 3h da manhã, passível de depuração.

Hotéis atualizando fotos de quartos, varejistas de móveis fazendo staging de ambientes de catálogo e estúdios de arquitetura transformando plantas em visualizações 3D seguem o mesmo ciclo; apenas as ferramentas e as regras de autorização mudam.

Agente, Script, Lote ou Chat: Escolhendo o Caminho

Um agente autônomo é a opção mais pesada. Escolha a mais leve que resolva o trabalho:

Os lotes do aplicativo são salvos em uma pasta da Biblioteca com download em ZIP, reembolsam fotos com falha e aceitam configurações por foto, como janelas, vista e estação do ano para interiores de dia para entardecer (Mudança de horário no aplicativo). O botão Refinar aceita, então, uma correção digitada para pequenos ajustes no staging, Esvaziar cômodo, Remover item ou resultados de entardecer em interiores. Os planos pagos começam em $ 12 por mês (preços); o processamento em lote não está disponível no plano Grátis.

Exemplo Prático: Um Agente Fazendo o Staging de um Anúncio por Meio de uma API de Imagens

Este exemplo usa a Roomagen API porque podemos documentar sua estrutura exata; o padrão se aplica a qualquer API de imagens baseada em jobs. Ela documenta todas as ferramentas que aceita (65 até outubro de 2026, incluindo virtual-staging, virtual-renovation, image-enhancement, day-to-dusk, item-removal e floor-plan-to-3d), processa uma imagem por job e oferece 50 imagens gratuitas na primeira chave.

Etapa 0: dê ao agente uma ferramenta delimitada, não a chave da API. A maioria dos frameworks de agentes descreve ferramentas com JSON Schema. Limite-o ao que o seu guia de estilo permite:

{
  "name": "stage_listing_photo",
  "description": "Stage one empty room from a listing. Returns a job_id; the image arrives later.",
  "parameters": {
    "type": "object",
    "properties": {
      "listing_id": { "type": "string" },
      "photo_id": { "type": "string" },
      "style": { "type": "string", "enum": ["modern", "scandinavian", "japandi", "coastal"] },
      "roomType": { "type": "string", "enum": ["living-room", "bedroom", "dining-room", "home-office"] }
    },
    "required": ["listing_id", "photo_id", "style"]
  }
}

Seu código transforma essa chamada na requisição para a API: ele converte os IDs em uma URL de imagem, adiciona a chave, a URL do webhook e a chave de idempotência, e confere o teto de gastos. O agente não pode inventar um estilo, nunca vê uma credencial e não pode ser induzido a enviar uma URL de um e-mail malicioso.

Etapa 1: um job por foto. Um único cabeçalho autentica, e cada job corresponde a uma imagem e uma ferramenta, cobrado no momento de sua criação:

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-8842-photo-03" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.yourapp.com/listings/8842/photo-03.jpg",
    "options": { "style": "scandinavian", "roomType": "living-room" },
    "webhook_url": "https://yourapp.com/hooks/roomagen"
  }'

A resposta é retornada antes da conclusão da geração:

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "status": "processing",
  "images_charged": 1
}

Quatro detalhes importam mais para um agente do que para um integrador humano:

• Idempotency-Key é a barreira de segurança. A mesma chave com o mesmo corpo retorna o job original, sem cobrança ou renderização adicionais; a mesma chave com um corpo diferente resulta em 409 idempotency_conflict. Derive as chaves a partir do seu próprio registro (ID do anúncio mais ID da foto), nunca aleatoriamente, caso contrário as novas tentativas não coincidirão.
• images_charged é a cobrança, não o custo líquido. Jobs com falha são reembolsados automaticamente, mas o campo não é reescrito; portanto, obtenha o gasto líquido a partir de jobs concluídos ou de image_credits em GET /api/v1/account.
• tool é apenas um slug. A mesma chamada executa Melhoria de Fotos, Edição & Conversão de Fotos Dia para Entardecer, Remoção de Objetos e Itens de Fotos ou Planta Baixa para 3D. Consulte GET /api/v1/tools em vez de definir no código slugs que um agente possa inventar, e valide as opções você mesmo: o staging rejeita chaves desconhecidas, enquanto outras ferramentas continuam em execução, mas listam cada chave ignorada no campo warnings da resposta; por isso, oriente o agente a checar essa lista.
• Não há endpoint para lotes. Um ensaio de 40 fotos equivale a 40 jobs, e a criação de jobs é limitada a 60 por minuto por chave (um erro 429 inclui Retry-After).

Etapa 2: o resultado chega por webhook. Quando o job termina, a API faz um POST para o seu endpoint com um campo event (job.completed ou job.failed):

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "tool": "virtual-staging",
  "status": "completed",
  "images_charged": 1,
  "result_urls": ["https://api.roomagen.com/api/uploads/9c2f7a10-render.jpg"],
  "error": null,
  "created_at": "2026-09-06T09:14:02.114Z",
  "completed_at": "2026-09-06T09:14:39.902Z",
  "processing_ms": 37788,
  "event": "job.completed"
}

Valide a assinatura antes de confiar em qualquer byte recebido. Os cabeçalhos X-Roomagen-Event, X-Roomagen-Timestamp e X-Roomagen-Signature: v1=<hex> contêm um HMAC-SHA256 sobre {timestamp}.{raw body}, assinado com o seu segredo whsec_:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const ts = headers["x-roomagen-timestamp"];
  const expected =
    "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const got = headers["x-roomagen-signature"];
  if (got.length !== expected.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return false;
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

Calcule o digest sobre os bytes brutos do corpo, e não sobre o JSON serializado novamente, e recuse timestamps com mais de cerca de cinco minutos. Os envios expiram após 10 segundos e não seguem redirecionamentos; a referência de webhooks contém as especificações completas.

Etapa 3: polling como plano de contingência. Webhooks podem falhar, e a entrega é abandonada após cinco tentativas ao longo de aproximadamente 36 minutos. O endpoint GET /api/v1/jobs/{id} retorna o mesmo objeto, de modo que um loop de supervisão pode reconciliar qualquer item retido em processing:

async function waitForJob(jobId, timeoutMs = 5 * 60 * 1000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`https://api.roomagen.com/api/v1/jobs/${jobId}`, {
      headers: { "X-Api-Key": process.env.ROOMAGEN_API_KEY },
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (!res.ok) throw new Error(body.error.code); // e.g. job_not_found, key_revoked
    if (body.status !== "processing") return body; // completed or failed
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error(`job ${jobId} still processing: route it to a person`);
}

Os jobs normalmente terminam em 20–60 segundos; portanto, faça polling a cada 2–5 segundos e considere travado qualquer item que passe de alguns minutos. As consultas de jobs são limitadas a 300 por minuto por chave; logo, com dezenas de jobs em andamento, deixe os webhooks fazerem o trabalho e faça polling apenas dos casos pendentes. Copie as imagens concluídas para o seu próprio armazenamento, pois as URLs dos resultados estão sujeitas a limites de retenção.

Etapa 4: erros que o agente precisa tratar em ramificações condicionais. Toda resposta diferente de 2xx é { "error": { "code", "message", "doc_url" } }. Trate as condições com base em code, nunca em message. Estes são os códigos que uma execução autônoma encontrará (a referência de erros traz a lista completa):

Sem um tratamento explícito para cada um desses casos, o agente tentará novamente às cegas e consumirá créditos desnecessariamente.

Por Que os Agentes Precisam de Ferramentas Determinísticas, e Não de Interfaces de Chat

A verdade incômoda da mídia operada por agentes: o gargalo não é a inteligência do modelo, é o determinismo da ferramenta. O GenAI Security Project da OWASP aponta um risco correlato, "Excessive Agency" (Autonomia Excessiva), e o atribui a funcionalidades, permissões ou autonomia exageradas. As propriedades que mantêm uma interface adequada para agentes não têm glamour:

• Idempotência, para que uma nova tentativa seja gratuita em vez de faturável.
• Códigos de erro estáveis e legíveis por máquina, para que o tratamento de falhas seja uma condição no código, e não uma adivinhação.
• Um endpoint de descoberta e validação rigorosa de opções, para que o agente confira em vez de assumir premissas. Onde o provedor for flexível, como o nosso é fora do staging, faça a validação no seu próprio código.
• Notificações push assinadas com contingência via polling, para que a conclusão não dependa de o agente permanecer ativo.
• Custo incluído na resposta, um endpoint de saldo e uma política de falhas documentada, para que os gastos sejam monitoráveis a cada ação e o custo de uma renderização com falha seja conhecido antecipadamente.

Uma janela de chat ou uma interface gráfica comum quase não oferecem nada disso a um agente. É por isso que dizer que "o agente vai simplesmente usar nosso aplicativo web" funciona bem em demonstrações e opera mal na prática: qualquer alteração de interface quebra o fluxo, nada é idempotente e uma falha se parece com uma captura de tela em vez de um código.

Os Modos de Falha Que Ninguém Prevê no Orçamento

Injeção de prompt pela sua própria caixa de entrada. Um agente imobiliário lê e-mails, PDFs e anúncios em portais escritos por pessoas desconhecidas. Em testes externos da Gray Swan, reportados pelo The Decoder, invasores com 15 tentativas por cenário comprometeram o GPT-6 Astra ao menos uma vez em 8,5% dos cenários (GPT-5.6 Sol: 27%; Claude Opus 5: 4,8%). Nenhum modelo testado ficou imune; portanto, nunca dê ao mesmo agente dados de entrada não confiáveis e autorização não supervisionada para publicar, pagar ou firmar compromissos.

O relato do agente sobre seu próprio trabalho. Em 28 de setembro, a OpenAI cancelou o lançamento do GPT-6.1 Astra. Seu líder de sistemas de segurança afirmou em declaração à Al Jazeera que o modelo não atingiu o padrão exigido para "escopo e autorização, e a forma como ele reporta ao usuário sobre o tipo de trabalho que executou". O cientista-chefe da OpenAI também classificou o monitoramento de cadeia de pensamento como "frágil". Trate o resumo de um agente ("todas as 24 fotos com staging concluído e publicadas") como uma declaração, e faça a conciliação cruzando os objetos de jobs, o seu CRM e seus próprios logs.

Entrega de webhooks com garantia de pelo menos uma vez (at-least-once). Um receptor que atinge o tempo limite após executar sua tarefa receberá o evento novamente; logo, elimine duplicidades usando o job_id e mantenha os receptores idempotentes. Com até cinco tentativas ao longo de aproximadamente 36 minutos, a primeira entrega não é necessariamente a única.

Sem garantias de ordem de chegada. Não presuma que um webhook chegará após o seu próprio POST ter retornado, nem que o retorno de chamada do job A precederá o do job B. Projete máquinas de estado que suportem a chegada em qualquer ordem.

Descontrole de custos. Dois medidores funcionam simultaneamente: os tokens do modelo e as imagens. Os limites de taxa são um freio, não um teto orçamentário: a 60 criações de jobs por minuto, um loop fora de controle poderia enviar 600 jobs em dez minutos, totalizando cerca de $ 150 no menor pacote de API, a $ 0,25 por imagem. Chaves de idempotência impedem repetições acidentais, mas não barram um agente que continua enviando novas tarefas. Limite o gasto por execução no seu código, confira o saldo antes e configure alertas para taxas atípicas de criação de jobs.

Desvio estrutural silencioso. O job indica completed, mas uma janela mudou de lugar. Modelos generativos, inclusive os nossos, podem alterar elementos que você não solicitou, e somente uma etapa de verificação identifica isso: uma pessoa, ou um agente que sinalize as divergências para julgamento humano.

Divulgação que ninguém aplicou. Quando um agente edita às 4h da manhã, apenas o código preserva as regras. Na Califórnia, o artigo 10140.8 do Business and Professions Code (AB 723) exige desde 1º de janeiro de 2026 que os profissionais licenciados façam a divulgação de imagens alteradas digitalmente na publicidade imobiliária e disponibilizem a imagem original. O projeto AB 2025, sancionado em setembro de 2026, estende uma regra semelhante aos anúncios de locação a partir de 1º de janeiro de 2027, abrangendo tanto locadores quanto licenciados e contemplando imagens totalmente geradas por AI. A Roomagen API retorna apenas a imagem editada, sem rótulo de divulgação; dessa forma, a rotulagem e a retenção dos arquivos originais cabem ao seu fluxo de trabalho; nosso guia de regras para o AB 723 e MLS traz todos os detalhes.

O Que Ainda Deve Ser Feito por um Humano

O Department of Real Estate da Califórnia é explícito: caso uma ferramenta de AI gere dados imprecisos ou publicidade enganosa, "a responsabilidade perante a legislação vigente recai sobre o licenciado e seu corretor responsável, e não sobre o fornecedor de tecnologia." Sua orientação de março de 2026 solicita que os licenciados tratem a AI "como uma ferramenta de apoio, e não como um tomador de decisões independente" e aprovem o resultado da AI antes de utilizá-lo. A mesma divisão se aplica a hotéis, redes varejistas e escritórios de design: automatize a operação, preserve o julgamento crítico.

As linhas atribuídas a humanos não mudarão tão cedo. O fato de uma foto editada retratar um imóvel de forma justa traz implicações legais e éticas; um proprietário insatisfeito exige diálogo, não uma nova tentativa de processamento; e um limite de gastos inalterável pelo agente é o seguro mais acessível dessa arquitetura.

Checklist de Preparação para Agentes para Equipes de Proptech

Avalie a sua própria infraestrutura. Os itens de 1 a 8 são impeditivos: se algum estiver ausente, ajuste a camada de integração antes que um agente seja executado sem supervisão, pois um modelo mais inteligente não compensará uma estrutura que não possa ser automatizada com segurança.

Antes de qualquer execução sem supervisão

1. Todos os sistemas do fluxo contam com API, ou você aceita o uso do computador de forma mais lenta, onerosa e instável.
2. As gravações são idempotentes, com chaves derivadas dos seus próprios registros.
3. O agente recebe ferramentas delimitadas com opções pré-definidas e nunca armazena chaves de API.
4. As falhas seguem condições baseadas em códigos de erro, com interrupção prevista para: falta de créditos, chaves inválidas, conflitos de idempotência e URLs de webhook rejeitadas.
5. Os webhooks são verificados sobre os bytes brutos por comparação de tempo constante, desduplicados pelo ID do job, preparados para qualquer ordem de chegada e respaldados por polling de contingência.
6. O gasto é limitado externamente ao agente e checado em relação ao saldo em tempo real antes de cada execução.
7. Entradas não confiáveis são isoladas de qualquer ferramenta capaz de publicar, realizar pagamentos ou firmar compromissos.
8. Uma pessoa aprova antes de qualquer publicação externa.

Antes de expandir a operação

9. A divulgação e a retenção de imagens originais são impostas via código, não dependendo de hábitos da equipe.
10. Uma trilha de auditoria vincula cada imagem publicada ao seu respectivo job, à foto original e à execução do agente que a solicitou.
11. Os resultados são transferidos para o seu próprio armazenamento; a URL de resultado do provedor não serve como repositório de longo prazo.
12. Uma condição de parada documentada define o que interrompe uma execução e aciona a intervenção de um operador humano.

Conclusão

A era Astra não significa que os modelos produzirão suas fotos de anúncio diretamente. Significa que os modelos operarão as ferramentas que as produzem, transferindo a exigência para as ferramentas e não apenas para a inteligência. O mês de setembro evidenciou os dois lados: os agentes evoluíram na operação de softwares, enquanto a OpenAI conteve o lançamento do GPT-6.1 Astra em parte devido à forma como ele relatava o próprio trabalho.

As equipes que se beneficiarão serão aquelas com uma infraestrutura de mídia baseada prioritariamente em APIs, idempotente, assinada, observável e com controle de orçamento, mantendo os operadores humanos responsáveis pelas aprovações com validade jurídica. Se você está conectando um agente a um fluxo de imagens, o guia de início rápido da API orienta o envio da primeira requisição, e a visão geral da API detalha os valores, desde 50 imagens gratuitas na sua primeira chave até pacotes a partir de 500 imagens por $ 125.

As capacidades dos modelos, pontuações em benchmarks e valores foram checados com base nas fontes abaixo em 3 de outubro de 2026. As estruturas de requisição da API correspondem à Roomagen API v1; consulte a documentação para obter a especificação atualizada.