用于房产照片的 AI 智能体：2026 年 API 操作指南

转变：从描述软件的模型到操作软件的智能体

直到最近，AI 模型与您的房产软件之间的关系都还只是指引性的。它可以告诉您在 CRM 中该写些什么，却无法替您打开 CRM。

这一界限在 2026 年 9 月发生了改变。OpenAI 于 9 月 3 日发布了 GPT-6 Astra，并附带这样一句话：“凡是您能在电脑上完成的事，Astra 都能替您办到”。报告显示，它在 OSWorld 2.0 计算机操作基准测试中的得分为 72.6%，每个任务耗时约 40 分钟；相比之下，其前代产品 GPT-5.6 Sol 的得分为 65.7%，耗时约为 75 分钟。Astra 输入文本和图像，且仅返回文本。按标准费率计算，其 API 费用为每 100 万输入 token 10 美元、每 100 万输出 token 50 美元，OpenAI 同时还列出了费用仅为其五分之一的 GPT-6.1 Sol（2 美元 / 10 美元）。Google 命名类似的 Project Astra 则是一个独立的研究原型，仅供由受信任测试者组成的有限群体使用。

对于房产媒体而言，这改变了按下按钮的人选。房源拍摄向来都是一连串的软件操作：上传、筛选、布置、增强、转换、标注、发布。如今，所有这些步骤都可以实现端到端自动化，这引出了大多数房产科技团队尚未解答的问题：若要让智能体安全运行，您的技术架构需要具备什么样的形态？

简而言之：智能体负责读取、分拣和校验；图像 API 负责生成像素；您的代码负责掌管密钥、预算和披露规则；而任何买家、租客或住客将要看到的内容，均须由人工完成审批。

关于 ChatGPT 的访问方式、完整价格和基准排名，请参阅房地产领域的 GPT-6 Astra。本文探讨的是背后的底层架构。

智能体驱动的媒体流水线运作机制

照片处理 API 让整套系统具备了可操作性：您通过 HTTPS 发送一张照片和一条指令（工具及其选项），便会收到一个可以追踪的任务，直至编辑后的图像准备就绪。围绕这一机制，针对单个房源的处理闭环如下所示：

步骤 2、3、6 和 8 是智能体模型发挥核心价值的环节。步骤 4 则是它交接工作的节点，因为 GPT-6 Astra 返回的是文本，而非图像（请参阅 GPT-6 Astra 能进行虚拟家居布置或生成图像吗？）。

智能体应当调用 API，而非在 Web 应用界面中逐一点选。计算机操作是针对没有 API 的软件而设立的兼容层。当 API 存在时，使用 API 速度更快、成本更低、确定性更强，而且更关键的是——在凌晨 3 点出现问题时它具有可调试性。

需要更新客房照片的酒店、需要为目录房间布置家居的家具零售商，以及将平面图转化为 3D 视图的建筑事务所，运行的都是这套相同的闭环；改变的仅仅是所用的工具和审核规则。

智能体、脚本、批量还是聊天：路径选择

自主智能体是最重型的一种选择。请选择能够胜任该任务的最轻量方案：

应用内的批量处理结果会保存在图片库文件夹中并支持 ZIP 下载，失败的照片会自动退款，且支持单张照片个性化设置，例如室内日景转黄昏照片编辑 & 转换（应用内的“时间变换”）中的窗户、窗外景观和季节设置。随后，对于家居布置、“清空房间”、“移除物体”或室内黄昏转换等略有偏差的结果，可以通过“修改”功能输入文字更正。付费方案起售价为每月 12 美元（定价）；免费方案不提供批量处理功能。

实操范例：智能体通过图像 API 布置房源

本范例使用 Roomagen API，因为我们可以明确其具体格式规范；该模式同样适用于任何基于任务机制的图像 API。它详细记录了所支持的每一项工具（截至 2026 年 10 月共 65 项，包括 virtual-staging、virtual-renovation、image-enhancement、day-to-dusk、item-removal 和 floor-plan-to-3d），每个任务处理一张图像，并在首个密钥上赠送 50 张免费图像额度。

步骤 0：为智能体提供功能受限的专用工具，而非直接提供 API 密钥。 大多数智能体框架使用 JSON Schema 来描述工具。请将其严格限制在您的风格指南允许的范围内：

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

您的代码会将该调用转换为实际的 API 请求：将 ID 解析为图像 URL，附带密钥、Webhook URL 以及幂等键，并核验支出上限。智能体无法凭空捏造风格，接触不到任何凭据，也不会被诱导提交来自恶意电子邮件的 URL。

步骤 1：每张照片对应一个任务。 使用一个请求头完成鉴权，每个任务包含一张图像和一个工具，并在创建时扣费：

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

在生成完成前，系统便会返回响应：

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

相比人类集成人员，有四个细节对智能体而言更为关键：

• Idempotency-Key 是安全护栏。 相同的密钥和请求体将返回原始任务，不会产生二次扣费或重复渲染；相同的密钥搭配不同的请求体则会返回 409 idempotency_conflict。请务必根据您自身的业务记录（房源 ID 加照片 ID）派生密钥，切勿随机生成，否则重试时将无法匹配。
• images_charged 代表单次扣费，而非最终净成本。 失败的任务会自动退款，但该字段不会被重写，因此净支出请以已完成的任务或 GET /api/v1/account 中的 image_credits 为准。
• tool 仅是一个标识符标识。 相同的调用方式可用于运行照片增强、日景转黄昏照片编辑 & 转换、照片物体移除与物品清除或平面图转3D。请通过 GET /api/v1/tools 动态获取，切勿硬编码那些可能被智能体凭空捏造的标识符，并且务必自行校验各项参数：虚拟家居布置会直接拒绝未知参数，而其他工具虽仍会继续运行，但会在响应的 warnings 列表中列出每个被忽略的参数，因此请让智能体仔细检查该列表。
• 不存在批量接口。 一套包含 40 张照片的拍摄任务即对应 40 个任务，每个密钥的任务创建速率限制为每分钟 60 次（返回 429 时会带有 Retry-After 请求头）。

步骤 2：通过 Webhook 接收结果。 当任务完成后，API 会向您的接口发送 POST 请求，其中包含 event 字段（job.completed 或 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"
}

在完全信任其中的任何数据之前，务必先验证签名。请求头 X-Roomagen-Event、X-Roomagen-Timestamp 和 X-Roomagen-Signature: v1=<hex> 携带了针对 {timestamp}.{raw body} 的 HMAC-SHA256 签名，该签名使用您的 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;
}

计算摘要时必须使用原始请求体字节，而非重新序列化后的 JSON，并且应拒绝距当前时间超过约五分钟的时间戳。推送请求在 10 秒后超时，且不跟随重定向；关于完整的协议约定，请参阅 Webhook 参考文档。

步骤 3：以轮询作为后备保障。 Webhook 可能会发送失败，在约 36 分钟内尝试 5 次后将被彻底放弃。由于 GET /api/v1/jobs/{id} 会返回相同的对象，监管循环可以据此对任何卡在 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); // 例如 job_not_found, key_revoked
    if (body.status !== "processing") return body; // completed 或 failed
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error(`job ${jobId} still processing: route it to a person`);
}

任务通常在 20 到 60 秒内完成，因此建议每隔 2 到 5 秒轮询一次，并将任何耗时超过数分钟的任务视为异常卡滞。每个密钥的任务查询速率限制为每分钟 300 次，因此当有数十个任务同时运行时，应当主要依赖 Webhook 处理，仅对滞后的任务进行轮询。请务必将处理完成的图像转存至您自己的存储空间，因为结果 URL 受到保留期限的限制。

步骤 4：智能体必须处理的分支错误。 所有非 2xx 的响应格式均为 { "error": { "code", "message", "doc_url" } }。代码逻辑中必须基于 code 进行分支判断，绝不能依据 message。以下是自主运行过程中会遇到的状态码（完整内容请参阅错误参考文档）：

如果未对上述每种情况编写明确的分支逻辑，智能体就会陷入盲目重试并白白消耗积分。

为什么智能体需要确定性的工具，而非聊天界面

智能体驱动媒体制作过程中一个令人难以忽视的事实是：瓶颈并不在于模型智力，而在于工具的确定性。 OWASP 的 GenAI 安全项目指出了一个相关风险——“过度代理”（Excessive Agency），并将其归因于过度的功能权限、过宽的访问控制或过高的自主权。能够让界面保持智能体友好特性的，恰恰是那些朴实无华的技术属性：

• 幂等性，确保重试无需额外付费，而不是每次都产生账单。
• 稳定的机器可读错误码，使失败处理成为清晰的代码分支，而非模糊的猜测。
• 服务发现接口与严格的参数校验，使智能体能够进行明确核验，而非凭空臆断。在服务提供商校验较为宽泛的环节（例如我们在虚拟布置之外的其他工具），请在您自己的代码中落实严密校验。
• 带有轮询后备机制的签名推送通知，确保任务完成不依赖于智能体是否持续保持唤醒状态。
• 在响应中返回成本、提供余额查询接口以及公布明确的失败退费政策，让每一项操作的支出都可被实时监控，并在渲染失败前就对其可能产生的成本心中有数。

聊天窗口或点击式图形界面几乎无法为智能体提供上述任何特性。这就是为什么“直接让智能体操作我们的 Web 应用”在演示时效果惊艳，实操起来却糟糕透顶：界面的任何细微改动都会导致运行崩溃，毫无幂等性可言，而且报错形式只是一张截图而非机器错误码。

容易被忽视的隐性失效模式

通过您自己的收件箱进行提示词注入。 房产经纪人需要读取陌生人撰写的电子邮件、PDF 和门户网站房源信息。在 The Decoder 报道的 Gray Swan 外部测试中，攻击者在每个场景尝试 15 次的情况下，有 8.5% 的场景至少成功入侵了 GPT-6 Astra 一次（GPT-5.6 Sol 的被入侵率为 27%；Claude Opus 5 为 4.8%）。没有任何受测模型能够完全免疫，因此切勿让同一个智能体既接收不可信输入，又拥有无需监管即可发布、付款或签约的权力。

智能体对其自身工作的汇报偏差。 9 月 28 日，OpenAI 取消了 GPT-6.1 Astra 的发布计划。其安全系统负责人在接受半岛电视台（Al Jazeera）采访时表示，该模型未能达到“权限范围与授权机制，以及向用户如实反馈其所完成工作类型的方式”的标准。OpenAI 的首席科学家也曾直言思维链监控手段“脆弱不堪”。请务必将智能体给出的摘要汇报（例如“所有 24 张照片均已布置并发布完毕”）仅仅视作一种单方面声明，并据此与具体的任务对象、您的 CRM 以及系统底层日志进行严格核对。

至少一次的 Webhook 投递机制。 处理程序如果在完成既定工作后响应超时，就会再次接收到相同的事件，因此务必基于 job_id 进行去重，并确保处理逻辑具备幂等性。由于系统会在约 36 分钟内最多尝试重试 5 次，首次投递的结果未必是唯一到达的通知。

不保证先后时序。 切勿假设 Webhook 一定会在您发出的 POST 请求返回之后才到达，也不要假设任务 A 的回调一定先于任务 B 到达。请编写能够容忍任意先后顺序的状态机。

成本失控。 系统中存在两项持续计费的计量器：模型的 token 消耗以及生成的图像张数。速率限制只是一道刹车闸，并不等同于预算控制：按照每分钟创建 60 个任务的速率，失控的死循环可能在十分钟内提交 600 个任务，按最小 API 套餐每张图像 0.25 美元计算，这将产生约 150 美元的费用。幂等键只能阻止重复提交，无法阻止智能体不断提交全新的任务。请务必在您的代码中限制单次运行的支出上限，在调用前先行核对余额，并在任务创建速率出现异常时触发告警。

隐蔽的结构偏移。 任务状态虽然显示为 completed（已完成），但画面中的一扇窗户可能发生了位移。包括我们自己在内的生成式模型，有时都会篡改您并未要求修改的内容，而唯有校验环节才能捕捉到这类问题：这需要人工核验，或者由智能体标记出差异交由人工裁决。

未按规定进行披露。 当智能体在凌晨 4 点进行编辑时，只有代码才能牢记合规规则。在加州，《商业和专业法典》第 10140.8 条（AB 723）自 2026 年 1 月 1 日起已明确要求持牌人必须在房地产广告中披露经过数字修改的图像，并提供原始图像以供查验。于 2026 年 9 月签署的 AB 2025 法案自 2027 年 1 月 1 日起将类似规则进一步扩展至租赁广告，适用对象涵盖住房提供方与持牌人，且包含完全由 AI 生成的图像。Roomagen API 仅返回编辑后的图像，不附带任何披露标注，因此对图像进行标注以及归档原始图像的工作必须在您的流水线中落实；详情请参阅我们的 AB 723 与 MLS 规则指南。

哪些职责仍必须由人工承担

加州房地产局（California Department of Real Estate）给出了极为明确的定性：如果 AI 工具产生了不准确的信息或误导性广告，“根据现行法律，责任由持牌人及其主管经纪人承担，而非技术提供商。”其于 2026 年 3 月发布的指引要求持牌人将 AI “视为支持工具而非独立决策者”，并在采信 AI 输出结果之前完成人工审批。对于酒店、零售商和设计工作室而言，这种职责划分同样适用：将繁重工作交给自动化，把关键判断留给人类。

这些需要人工介入的环节在短期内不会改变。编辑后的照片能否客观公正地呈现房产原貌承载着法律与道德分量；对房源展示不满的卖家需要的是一场面对面的沟通，而不是机械式的程序重试；而在您的架构中设立一个智能体无法擅自修改的支出上限，则是成本最低的保险策略。

房产科技团队的“智能体就绪度”自查清单

请为您的技术架构打分。第 1 至第 8 项为一票否决项：只要缺少其中任何一项，在允许智能体在无人值守状态下运行前，都必须先修复集成接口，因为再聪明的模型也无法弥补一个无法安全实现自动化的系统缺陷。

在开展任何无人值守运行之前

1. 流水线中的每个系统都必须具备 API，否则您就必须接受计算机操作在速度上更慢、成本上更高且稳定性上更脆弱的现实。
2. 写操作必须具备幂等性，且密钥须派生自您自身的业务记录。
3. 智能体仅能使用参数明确受限的狭义工具，且绝不能持有 API 密钥。
4. 失败处理必须针对错误码设计清晰的分支逻辑，并建立中止清单：积分耗尽、密钥无效、幂等冲突、Webhook URL 被拒等。
5. Webhook 必须基于原始字节使用恒定时间比较算法进行校验，依据任务 ID 进行去重，能够容忍任意到达时序，并辅以轮询机制作为后备保障。
6. 支出上限须独立于智能体之外进行强制约束，并在每次运行前对比实时余额进行核验。
7. 不可信的输入内容必须严格隔离，切勿让其接触到任何具备发布、支付或签署合同权限的工具。
8. 任何公开对外发布的内容均须经过人工批准。

在进一步扩大规模之前

9. 披露机制与原始图像归档留存必须在代码层面强制执行，切勿依赖操作习惯。
10. 建立完整的审计追踪链，将每张已发布的图像与其任务记录、原始底图以及发起该请求的智能体运行批次绑定。
11. 将处理结果同步转存至您自己的存储系统；服务提供商返回的结果 URL 并不等同于永久归档空间。
12. 制定完备的停机条件文档，明确在何种情况下必须立即终止运行并唤醒人工介入。

总结

Astra 时代的到来，并不意味着模型会亲自替您拍摄房源照片。它意味着模型将负责操作制作这些照片的各种工具，这便将核心要求从模型智力转移到了工具本身的工程质量上。9 月的行业动态清晰展现了这一体两面：智能体在操作软件方面的能力日益精进，而 OpenAI 却推迟了 GPT-6.1 Astra 的发布，部分原因正是由于它在汇报自身工作成果时的不可靠表现。

最终能从中获益的团队，必将建立起一套以 API 为核心、具备幂等性、带有安全签名、运行状态透明可观测且设置了严格预算上限的媒体架构，并由人类牢牢把控承载法律责任的审批节点。如果您正准备将智能体接入图像处理流水线，API 快速入门将带领您完成首次请求调用，而 API 概览则涵盖了详尽的定价信息，包括首个密钥赠送的 50 张免费图像，以及 125 美元起购的 500 张图像套餐。

模型功能、基准测试分数与价格数据已于 2026 年 10 月 3 日与下文来源进行了对照核实。API 请求格式严格遵循 Roomagen API v1 规范；最新接口标准请查阅官方开发文档。