Agents IA pour photos immobilières : Guide API pour 2026

Le tournant : des modèles qui décrivent les logiciels aux agents qui les manipulent

Jusqu'à récemment, la relation d'un modèle d'IA avec votre logiciel immobilier était purement consultative. Il pouvait vous indiquer quoi écrire dans le CRM. Il ne pouvait pas ouvrir le CRM.

Cette frontière a bougé en septembre 2026. OpenAI a annoncé GPT-6 Astra le 3 septembre avec ce slogan : « Tout ce que vous pouvez faire sur un ordinateur, Astra peut le faire pour vous », et affiche un score de 72,6 % sur le benchmark d'utilisation d'ordinateurs OSWorld 2.0 à environ 40 minutes par tâche, contre 65,7 % en près de 75 minutes pour son prédécesseur, GPT-5.6 Sol. Astra reçoit du texte et des images et ne renvoie que du texte. Son API coûte 10 $ par million de jetons d'entrée et 50 $ par million de jetons de sortie au tarif standard, et OpenAI propose également GPT-6.1 Sol à un cinquième de ce prix (2 $ / 10 $). Le projet au nom similaire de Google, Project Astra, est un prototype de recherche distinct utilisé par un groupe restreint de testeurs de confiance.

Pour les médias immobiliers, cela change qui appuie sur les boutons. Une séance photo d'annonce a toujours été une séquence d'opérations logicielles : téléverser, sélectionner, meubler, améliorer, convertir, étiqueter, publier. Toutes peuvent désormais être automatisées de bout en bout, ce qui soulève une question à laquelle la plupart des équipes de proptech n'ont pas encore répondu : à quoi votre infrastructure doit-elle ressembler pour qu'un agent puisse la piloter en toute sécurité ?

La réponse courte : l'agent lit, trie et vérifie ; une API d'image fabrique les pixels ; votre code conserve les clés, le budget et les règles de divulgation ; et une personne approuve tout ce qu'un acheteur, locataire ou client verra.

L'accès à ChatGPT, les tarifs complets et les classements aux benchmarks se trouvent dans GPT-6 Astra for Real Estate. Cet article s'intéresse aux rouages techniques.

À quoi ressemble un pipeline média piloté par un agent

Une API de traitement de photos est ce qui rend tout cela pilotable : vous envoyez une photo et une instruction (un outil et ses options) via HTTPS, et vous recevez en retour une tâche que vous pouvez suivre jusqu'à ce que l'image retouchée soit prête. Autour de cela, la boucle pour une annonce ressemble à ceci :

Les étapes 2, 3, 6 et 8 sont celles où un modèle agentique justifie son utilisation. L'étape 4 est celle du passage de relais, car GPT-6 Astra renvoie du texte et non des images (voir Can GPT-6 Astra Do Virtual Staging or Generate Images?).

L'agent doit appeler une API, et non cliquer sur une interface web. L'interaction directe avec l'ordinateur est une couche de compatibilité pour les logiciels dépourvus d'API. Lorsqu'une API existe, l'utiliser est plus rapide, plus économique, déterministe et, ce qui compte à 3 heures du matin, débogable.

Les hôtels qui actualisent les photos de leurs chambres, les distributeurs de mobilier qui mettent en scène leurs pièces de catalogue et les cabinets d'architecture qui transforment des plans en vues 3D exécutent la même boucle ; seuls les outils et les règles de validation changent.

Agent, script, traitement par lot ou chat : choisir la bonne voie

Un agent autonome est l'option la plus lourde. Choisissez la plus légère qui remplit la mission :

Les traitements par lot de l'application arrivent dans un dossier de la Bibliothèque avec un téléchargement ZIP, remboursent les photos échouées et acceptent des réglages photo par photo, tels que les fenêtres, la vue et la saison pour les intérieurs jour en crépuscule (Changement horaire dans l'application). Le bouton Retoucher accepte ensuite une correction tapée au clavier pour ajuster un résultat presque parfait en home staging, Vider la pièce, Supprimer un objet ou des rendus crépusculaires intérieurs. Les forfaits payants débutent à 12 $ par mois (tarifs) ; le traitement par lot n'est pas disponible sur le forfait Gratuit.

Exemple concret : un agent meublant virtuellement une annonce via une API d'image

Cet exemple utilise l'API Roomagen car nous pouvons détailler sa structure exacte ; le modèle se transpose à n'importe quelle API d'image basée sur des tâches. Elle documente chaque outil qu'elle accepte (65 à la date d'octobre 2026, incluant virtual-staging, virtual-renovation, image-enhancement, day-to-dusk, item-removal et floor-plan-to-3d), traite une image par tâche, et offre 50 images gratuites sur la première clé.

Étape 0 : donner à l'agent un outil au périmètre restreint, pas la clé d'API. La plupart des frameworks d'agents décrivent les outils avec JSON Schema. Limitez-le à ce qu'autorise votre charte graphique :

{
  "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"]
  }
}

Votre code transforme cet appel en requête API : il résout les identifiants pour obtenir une URL d'image, ajoute la clé, l'URL de webhook et la clé d'idempotence, et vérifie le plafond de dépenses. L'agent ne peut pas inventer de style, ne voit jamais d'identifiant d'accès, et ne peut pas être manipulé pour soumettre une URL provenant d'un e-mail malveillant.

Étape 1 : une tâche par photo. Un seul en-tête authentifie la requête, et chaque tâche correspond à une image et un outil, facturée dès sa création :

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

La réponse est renvoyée avant la fin de la génération :

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

Quatre détails comptent davantage pour un agent que pour un intégrateur humain :

• Idempotency-Key est le garde-fou. La même clé et le même corps renvoient la tâche d'origine, sans seconde facturation ni nouveau rendu ; la même clé avec un corps différent reçoit 409 idempotency_conflict. Dérivez toujours les clés de vos propres enregistrements (identifiant d'annonce plus identifiant de photo), jamais au hasard, sinon les tentatives de réexécution ne correspondront pas.
• images_charged correspond à la facturation initiale, pas au coût net. Les tâches échouées sont automatiquement remboursées, mais le champ n'est pas réécrit : calculez donc les dépenses nettes à partir des tâches terminées ou du champ image_credits dans GET /api/v1/account.
• tool n'est qu'un identifiant texte (slug). Le même appel exécute l'Amélioration de photos, la Retouche & Conversion Photo Jour en Crépuscule, la Suppression d'objets et d'éléments par IA dans les photos ou le Plan d'étage en 3D. Interrogez GET /api/v1/tools au lieu d'inscrire en dur des identifiants qu'un agent pourrait inventer, et validez vous-même les options : le home staging rejette les clés inconnues, tandis que les autres outils s'exécutent tout de même mais signalent chaque clé ignorée dans la liste warnings de la réponse ; faites en sorte que l'agent vérifie cette liste.
• Il n'existe aucun point de terminaison par lot. Une séance de 40 photos correspond à 40 tâches, et la création de tâches est limitée à 60 par minute et par clé (une erreur 429 contient l'en-tête Retry-After).

Étape 2 : le résultat arrive par webhook. Lorsque la tâche se termine, l'API la transmet par un POST à votre point de terminaison avec un champ 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"
}

Vérifiez la signature avant d'accorder la moindre confiance à ces octets. Les en-têtes X-Roomagen-Event, X-Roomagen-Timestamp et X-Roomagen-Signature: v1=<hex> transportent un HMAC-SHA256 sur {timestamp}.{raw body}, calculé avec votre clé secrète 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;
}

Calculez l'empreinte sur les octets bruts du corps, et non sur un JSON re-sérialisé, et rejetez les horodatages datant de plus de cinq minutes environ. Les envois expirent au bout de 10 secondes et ne suivent pas les redirections ; la documentation des webhooks contient le contrat complet.

Étape 3 : le sondage (polling) comme solution de secours. Les webhooks peuvent échouer, et une distribution est abandonnée après cinq tentatives étalées sur environ 36 minutes. GET /api/v1/jobs/{id} renvoie le même objet, permettant à une boucle de supervision de débloquer toute tâche coincée à l'état 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`);
}

Les tâches se terminent généralement en 20 à 60 secondes : sondez donc toutes les 2 à 5 secondes et considérez toute tâche dépassant quelques minutes comme bloquée. Les consultations de tâches sont limitées à 300 par minute et par clé ; par conséquent, avec des dizaines de tâches en cours, laissez les webhooks faire le travail et n'interrogez que les retardataires. Copiez les images finalisées sur votre propre espace de stockage, car les URL de résultats sont soumises à des limites de conservation.

Étape 4 : les erreurs sur lesquelles l'agent doit bifurquer. Chaque réponse autre que 2xx prend la forme { "error": { "code", "message", "doc_url" } }. Définissez vos branchements selon le code, jamais selon le message. Voici les codes qu'une exécution autonome rencontrera (la documentation des erreurs les liste tous) :

Sans un branchement explicite pour chacun de ces cas, un agent tentera aveuglément de relancer l'opération et consumera vos crédits.

Pourquoi les agents ont besoin d'outils déterministes et non d'interfaces de chat

La vérité inconfortable des médias pilotés par des agents : le goulot d'étranglement n'est pas l'intelligence du modèle, mais le déterminisme de l'outil. Le projet de sécurité GenAI de l'OWASP cite un risque connexe, l'« agence excessive » ("Excessive Agency"), et en trouve l'origine dans une surabondance de fonctionnalités, de permissions ou d'autonomie. Les propriétés qui rendent une interface adaptée aux agents sont peu spectaculaires :

• L'idempotence, afin qu'une tentative supplémentaire soit gratuite plutôt que facturable.
• Des codes d'erreur stables et lisibles par machine, pour que le traitement des échecs devienne une condition d'exécution logique, et non une supposition.
• Un point de terminaison de découverte et une validation stricte des options, de sorte que l'agent vérifie plutôt qu'il ne présume. Lorsqu'un fournisseur se montre indulgent, comme le nôtre en dehors du home staging, validez dans votre propre code.
• Des notifications push signées complétées par une alternative de sondage, afin que la validation ne dépende pas du maintien de l'agent en état d'éveil.
• Le coût dans la réponse, un point de terminaison pour le solde et une politique d'échec publiée, afin que les dépenses soient observables par action et que le coût d'un rendu manqué soit connu à l'avance.

Une fenêtre de discussion ou une interface utilisateur graphique n'offre pratiquement rien de tout cela à un agent. C'est pourquoi l'approche consistant à dire que « l'agent n'a qu'à utiliser notre application web » fonctionne bien en démonstration mais se révèle médiocre en pratique : chaque modification de l'interface brise le flux, rien n'est idempotent, et un dysfonctionnement se manifeste par une capture d'écran plutôt que par un code précis.

Les modes de défaillance que personne ne budgétise

L'injection de prompt via votre propre boîte de réception. Un agent immobilier lit des e-mails, des PDF et des annonces de portails rédigés par des inconnus. Lors des tests externes menés par Gray Swan et rapportés par The Decoder, des assaillants disposant de 15 tentatives par scénario ont compromis GPT-6 Astra au moins une fois dans 8,5 % des scénarios (GPT-5.6 Sol : 27 % ; Claude Opus 5 : 4,8 %). Aucun modèle testé n'était immunisé : ne confiez donc jamais au même agent à la fois des données d'entrée non fiables et l'autorité non supervisée de publier, payer ou contracter.

Le compte-rendu que fait l'agent de son propre travail. Le 28 septembre, OpenAI a annulé le lancement de GPT-6.1 Astra. Sa responsable des systèmes de sécurité a déclaré à Al Jazeera que le modèle n'atteignait pas le niveau requis concernant « le périmètre et l'autorisation, ainsi que la manière dont il communique à l'utilisateur la nature du travail qu'il a effectué ». Le directeur scientifique d'OpenAI a également qualifié la surveillance du raisonnement interne (chain-of-thought) de « fragile ». Traitez tout récapitulatif fourni par un agent (« 24 photos meublées et publiées ») comme une simple affirmation, et comparez-le aux objets des tâches, à votre CRM et à vos propres journaux.

La distribution de webhooks au moins une fois (at-least-once). Un gestionnaire de webhook qui expire après avoir accompli sa tâche recevra à nouveau l'événement : dédupliquez donc sur le job_id et gardez vos gestionnaires idempotents. Avec un maximum de cinq tentatives réparties sur environ 36 minutes, la première distribution n'est pas nécessairement la seule.

L'absence de garantie quant à l'ordre d'arrivée. Ne supposez pas qu'un webhook arrivera après la réponse de votre propre requête POST, ni que la notification de la tâche A précédera celle de la tâche B. Concevez des machines à états tolérant une arrivée dans n'importe quel ordre.

L'emballement des coûts. Deux compteurs tournent : les jetons du modèle et les images. Les limites de débit sont un frein, pas un budget : à 60 créations de tâches par minute, une boucle hors de contrôle pourrait soumettre 600 tâches en dix minutes, soit environ 150 $ au tarif de 0,25 $ par image du plus petit pack d'API. Les clés d'idempotence bloquent les réémissions à l'identique, pas un agent qui continue de générer de nouveaux travaux. Plafonnez la dépense par exécution dans votre code, vérifiez le solde au préalable et activez des alertes en cas de cadences inhabituelles de création de tâches.

La dérive structurelle silencieuse. La tâche indique completed, mais une fenêtre a été déplacée. Les modèles génératifs, y compris les nôtres, peuvent modifier des éléments que vous n'avez pas demandé de toucher, et seule une étape de vérification permet de s'en apercevoir : une personne, ou un agent qui met en évidence les différences pour les soumettre à l'appréciation d'un être humain.

La divulgation que personne n'a appliquée. Quand un agent procède à des modifications à 4 heures du matin, seul le code se souvient des règles. En Californie, l'article 10140.8 du Business and Professions Code (loi AB 723) impose aux titulaires de licence depuis le 1er janvier 2026 de divulguer les images altérées numériquement dans les publicités immobilières et de mettre l'original à disposition. La loi AB 2025, promulguée en septembre 2026, étend une règle similaire aux annonces de location à compter du 1er janvier 2027, s'appliquant aussi bien aux bailleurs qu'aux titulaires de licence et aux images entièrement générées par IA. L'API Roomagen ne renvoie que l'image retouchée, sans étiquette de divulgation : l'étiquetage et la conservation des originaux incombent donc à votre propre pipeline ; notre guide de conformité aux règles de l'AB 723 et des MLS en détaille les aspects.

Ce qui relève toujours d'un être humain

Le Department of Real Estate de Californie est sans équivoque : si un outil d'IA produit des informations inexactes ou une publicité trompeuse, « la responsabilité en vertu de la législation en vigueur incombe au titulaire de la licence et à son courtier responsable, et non au fournisseur de la technologie ». Son avis de mars 2026 invite les titulaires de licence à considérer l'IA « comme un outil de soutien plutôt que comme un décideur indépendant » et à valider les productions de l'IA avant de s'y fier. Le même partage des rôles s'applique aux hôtels, aux commerçants et aux cabinets d'architecture : automatisez l'exécution, conservez le discernement.

Ces attributions humaines ne changeront pas de sitôt. Déterminer si une photo retouchée présente fidèlement un bien engage une responsabilité juridique et éthique ; un vendeur mécontent a besoin d'un échange humain, pas d'une tentative de génération supplémentaire ; et un plafond financier que l'agent ne peut pas contourner reste l'assurance la plus économique de cette architecture.

La liste de contrôle d'adéquation aux agents pour les équipes proptech

Évaluez votre propre infrastructure. Les points 1 à 8 sont bloquants : si l'un d'eux fait défaut, assainissez votre surface d'intégration avant de faire tourner un agent sans surveillance, car un modèle plus intelligent ne compensera jamais une architecture qui ne peut être automatisée en toute sécurité.

Avant toute exécution sans surveillance

1. Chaque système de la chaîne dispose d'une API, faute de quoi vous acceptez l'utilisation directe de l'ordinateur comme étant plus lente, plus coûteuse et plus fragile.
2. Les écritures sont idempotentes, avec des clés dérivées de vos propres enregistrements.
3. L'agent reçoit des outils au périmètre étroit avec des options énumérées et ne détient jamais de clé d'API.
4. Le traitement des échecs bifurque selon les codes d'erreur, avec une liste de cas d'arrêt : pas de crédits, clés invalides, conflits d'idempotence, URL de webhooks rejetées.
5. Les webhooks sont vérifiés sur les octets bruts avec une comparaison en temps constant, dédupliqués par identifiant de tâche, tolérants à tout ordre d'arrivée et relayés par un système d'interrogation régulière (poller).
6. Les dépenses sont plafonnées hors de portée de l'agent et comparées au solde en temps réel avant chaque exécution.
7. Les données d'entrée non fiables sont isolées de tout outil capable de publier, payer ou contracter.
8. Une personne valide avant que quoi que ce soit ne soit rendu public.

Avant de passer à l'échelle

9. La divulgation et la conservation des images originales sont appliquées dans le code, et non laissées aux habitudes.
10. Une piste d'audit relie chaque image publiée à sa tâche, à sa photo source et à la session de l'agent qui l'a demandée.
11. Les résultats sont copiés sur votre propre espace de stockage ; l'URL de résultat d'un prestataire ne constitue pas une archive.
12. Une condition d'arrêt documentée définit ce qui interrompt une exécution et alerte un être humain.

En résumé

L'ère d'Astra ne signifie pas que les modèles vont fabriquer vos photos d'annonce. Elle signifie que les modèles vont piloter les outils qui les fabriquent, ce qui reporte l'exigence sur les outils plutôt que sur l'intelligence pure. Le mois de septembre a montré ces deux réalités : les agents sont devenus plus habiles à utiliser les logiciels, et OpenAI a freiné la sortie de GPT-6.1 Astra en partie en raison de la façon dont le modèle rendait compte de ses propres actions.

Les équipes qui tireront leur épingle du jeu s'appuieront sur une chaîne média conçue en priorité pour les API, idempotente, signée, observable et plafonnée, où les humains conservent les validations juridiquement engageantes. Si vous connectez un agent à un pipeline d'images, le guide de démarrage rapide de l'API détaille la première requête, et la présentation de l'API couvre la tarification, depuis les 50 images gratuites sur votre première clé jusqu'aux packs à partir de 500 images pour 125 $.

Les capacités des modèles, les scores de benchmarks et les tarifs ont été vérifiés auprès des sources ci-dessous le 3 octobre 2026. La structure des requêtes API correspond à la version 1 de l'API Roomagen ; veuillez consulter la documentation pour connaître les spécifications à jour.