如何为您的应用添加虚拟家居布置：开发者 API 教程

为应用程序添加虚拟家居布置功能归结为一个闭环：您的后端将房间照片作为任务发送给虚拟家居布置 API，提供商在后台进行渲染，您的应用程序收集结果，将其与原图存放在一起，并根据目标平台的要求展示所需的任何披露信息。本教程将基于 Roomagen API 构建该闭环，提供 cURL、Node.js 和 Python 代码示例，并保持设计的可移植性以便适配其他提供商。

集成概览

1. 从您的服务器将每张照片作为任务发送：带有 Idempotency-Key 的 POST /v1/jobs。
2. 在执行任何其他操作之前，先存储返回的 job_id。
3. 通过带签名的 Webhook 接收已完成的任务，并通过 GET /v1/jobs/{id} 对遗漏的任务进行对账调和。
4. 重新转存结果，在旁边保留原图，并将披露数据带入每次导出中。

您的构建目标：家居布置功能的架构

在本教程结束时，您的应用程序将能够接收房间照片并显示同一房间布置家具后的版本，根据 Roomagen 的文档，通常耗时 20 到 60 秒。此处的其他所有设计都是为了使该闭环在生产级负载下可靠运行。同样的闭环也适用于房源门户网站、摄影交付平台、宣传空置单元的物业管理软件、在客户自有房间上推介方案的室内设计应用，以及展示选定风格房间效果的家具零售商。

渲染需要数十秒，时间太长以至于无法保持 HTTP 请求持续打开，因此采用了异步设计：提交任务，立即获取任务 ID，稍后收集结果。家居布置运行一个多步骤流水线（场景分析，然后是提示词，接着是生成），因此比日景转黄昏等工具慢：在 Roomagen 截至 2026年10月1日 的 30 天生产数据中，API 家居布置任务的中位数耗时约 45 秒，而日景转黄昏和平面图转3D约为 25 秒。

Roomagen 是一个 AI 照片编辑与虚拟家居布置平台，其 Web 应用中包含 40+ 款工具；API 文档记录了在单一任务端点下支持的所有工具（截至 2026年10月 为 65 款）。其图像工具运行在 Google 的 Gemini 图像模型上，API 增加了家居布置流水线、任务处理、失败渲染的自动退款以及带签名的 Webhook。

开始之前：密钥、环境和图像要求

获取密钥。 Roomagen 的 API 自 2026年8月30日 公开发布以来一直支持自助开通；无需等待名单。使用 Roomagen 账户登录开发者门户，验证您的邮箱并创建密钥，如 API 快速入门 所述。您的首个密钥将获得 50 张免费图片（每个账户限一次），足够构建和测试本指南中的所有内容。在账户购买套餐包之前，每次渲染都带有 Roomagen 水印，因此请仅将其用于构建和测试，切勿用于公开发布。

密钥由 rmg_live_ 加上 64 位十六进制字符组成，在 X-Api-Key 请求头中发送，门户网站对每个密钥仅显示一次。请将其保存在服务端机密存储中；切勿在浏览器 JavaScript 或移动应用中直接发布，否则任何人都可以提取它并消耗您的余额。

环境。 一个账户最多可持有 10 个有效密钥，因此可以按环境各创建一个，以便在不影响其他密钥的情况下吊销任意一个。这里没有测试模式：每个密钥都是在线环境生效的，并且一个账户下的密钥共享一个图片余额、一个门户 Webhook 和一个签名机密，因此请为开发环境的任务设置独立的每任务 webhook_url。出于安全设计，系统不设轮换按钮：先创建新密钥并部署，然后吊销旧密钥。

图像输入。

建议优先使用 image_url：请求保持轻量，省去了 base64 带来的 33% 额外开销，并且由于抓取发生在处理 POST 请求期间，签名 URL 仅需在该请求期间有效即可。请发送全尺寸导出图，每张画面一个房间，水平拍摄且光照合理；模型只能保留它能看到的细节。

在代码中检查余额。 GET /v1/account 返回 image_credits，即您的余额仍可渲染的图片数。现在就将低余额告警接入此接口：当余额无法支付任务时，POST /v1/jobs 将返回 402 insufficient_credits 且不会创建任务。

第 1 步：提交家居布置任务

通过一个 POST 请求创建任务：指定工具、图像、选项以及可选的每任务 webhook_url（若未提供，Roomagen 将使用门户中保存的账户 Webhook，或者由您主动轮询）。

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: $ROOMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: photo-4821-3-stage" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.example.com/rooms/4821-3.jpg",
    "options": { "style": "scandinavian", "roomType": "living-room", "mode": "empty-room" },
    "webhook_url": "https://app.example.com/hooks/roomagen"
  }'

在渲染完成之前，接口即会返回状态码 201 的响应：

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

在 Node.js 18+ 后端中的相同调用：

async function submitStagingJob(photo) {
  const res = await fetch("https://api.roomagen.com/api/v1/jobs", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.ROOMAGEN_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": `photo-${photo.id}-stage`, // 源自您的记录，切勿使用随机值
    },
    body: JSON.stringify({
      tool: "virtual-staging",
      image_url: photo.signedUrl,
      options: { style: photo.style, roomType: photo.roomType, mode: "empty-room" },
      webhook_url: "https://app.example.com/hooks/roomagen",
    }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  await db.query(
    "INSERT INTO staging_jobs (photo_id, job_id, status, images_charged) VALUES ($1, $2, 'processing', $3)",
    [photo.id, body.job_id, body.images_charged],
  );
  return body.job_id;
}

家居布置比其他工具更为严格。style 为必填项，选项使用驼峰命名法（camelCase），且下列列表之外的任何键（包括 room_type、resolution、tier 和 customPrompt）均会被拒绝并返回 invalid_request。家居布置始终以 2K 渲染并扣除 1 张图片额度。

这三种模式对应 Roomagen Web 应用中的家居布置模式，因此您的产品团队可以在编写代码之前先行体验：用于空房间的 AI virtual staging（虚拟家居布置）、用于 restyle 的 redesign a furnished room（重新设计已布置的房间） 以及用于 recreate 的 Room Repurpose（房间功能转换）。

在做任何事之前先持久化。 将 job_id 和 images_charged 与您自己的数据记录关联保存。Idempotency-Key 请求头（最多 128 个字符，作用域限定于您的 API 密钥）可确保重试安全：携带相同请求体的相同键将返回原始任务，不会发生重复扣费。请基于您的业务记录生成幂等键，以便在系统崩溃后能够重建，并重新发送完全相同的请求体：相同键若携带不同的请求体（包括重新签名的 image_url），将返回 409 idempotency_conflict。

第 2 步：处理完成状态 —— Webhook 与轮询对比

获知任务完成有两种方式，生产级集成通常结合使用两者。

优先使用 Webhook，并以轮询作为兜底兜底。 Roomagen 的文档将 Webhook 称为“一种优化手段，而非最终记录系统”，因为重试窗口期过后投递就会被放弃。但仅靠轮询也无法承载大规模调用：按 3 秒间隔计算，每个任务每分钟需要消耗 20 次请求，因此 GET /v1/jobs/{id} 每分钟 300 次的限制仅能支持约 15 个任务同时轮询。

设置端点。 在门户的 Webhook 卡片中保存一个 https 端点，请使用最终的 URL，因为重定向不会被追踪跟随。将 whsec_ 签名机密像密码一样严格保管，并在调试签名验证时使用 Send test event 发送一次 job.test 投递测试。针对每个任务设置的 webhook_url 使用相同的机密。

const crypto = require("crypto");
const express = require("express");
const app = express();

// 在该路由上使用原始请求体（Raw body），挂载在任何全局 express.json() 之前
app.post("/hooks/roomagen", express.raw({ type: "application/json" }), async (req, res) => {
  const ts = req.get("X-Roomagen-Timestamp");
  const sig = req.get("X-Roomagen-Signature");
  if (!ts || !sig) return res.sendStatus(401);

  const expected = "v1=" + crypto
    .createHmac("sha256", process.env.ROOMAGEN_WEBHOOK_SECRET) // whsec_...
    .update(`${ts}.`)
    .update(req.body) // 原始字节，切勿使用重新序列化的 JSON
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (sig.length !== expected.length || !fresh ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const job = JSON.parse(req.body);
  if (job.event === "job.test") return res.sendStatus(200);

  // 幂等处理：仅在首次投递（或轮询）时将数据行移出 "processing" 状态
  const { rowCount } = await db.query(
    "UPDATE staging_jobs SET status = $1, result_urls = $2, error = $3 WHERE job_id = $4 AND status = 'processing'",
    [job.status, job.result_urls, job.error, job.job_id],
  );
  if (rowCount === 1 && job.status === "completed") {
    await queue.add("store-results", { jobId: job.job_id }); // 在请求处理路径之外执行下载
  }
  res.sendStatus(200);
});

必须注意四个细节：

1. 基于原始字节验证。 请求头为 v1= 加上 {X-Roomagen-Timestamp}.{raw body} 的十六进制 HMAC-SHA256 签名；重新序列化的 JSON 将无法匹配。
2. 在恒定时间内比较，然后检查新鲜度。 Node 的 timingSafeEqual 在长度不等时会抛出异常，因此请先比对长度。拒绝超过约五分钟的时间戳可防范重放攻击，这与 Stripe Webhook 文档 所描述的防御机制相同；请确保服务器时钟同步。
3. 快速应答。 Roomagen 等待 2xx 响应的超时时间为 10 秒；任何其他响应（包括超时）均被视为失败尝试并将进行重试。
4. 保持幂等。 投递采用至少一次投递机制且不保证顺序，而且您的轮询程序可能已经完成了任务，因此请基于 job_id 进行去重。

对于轮询（在开发期间或作为对账调和机制使用），Python 版本的实现非常精简：

import os, time, requests

API = "https://api.roomagen.com/api/v1"
HEADERS = {"X-Api-Key": os.environ["ROOMAGEN_API_KEY"]}

def wait_for_job(job_id, interval=3, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        job = r.json()
        if job["status"] != "processing":
            return job  # "completed" 或 "failed"；两者皆为最终状态
        time.sleep(interval)
    return None  # 仍在处理中：留给对账调和机制处理

任务结束时状态为 completed（带有 result_urls），或为 failed（在 error 中带有原因并自动退款）；记录 processing_ms 以监控延迟。针对几分钟后仍处于 processing 的任务，每隔一两分钟运行一次对账调和机制。切勿仅仅因为定时器超时就将处理缓慢的任务标记为失败：它可能仍在完成中，并且在创建时已扣费。

第 3 步：向用户交付结果

已完成的任务将返回 result_urls，这是一个渲染后的 JPEG 图像数组。请勿对这些链接进行盗链引用。

重新转存结果。 Roomagen 是从其自有存储中提供结果的，受账户保留策略约束，因此后台任务应在任务完成后立即下载每张图像，将其写入您自己的存储桶（S3、R2、GCS 等），并通过您的 CDN 进行分发。这样您的图像就绝不会依赖供应商的保留策略。

在输出旁边保留原图。 将源照片和经过虚拟家居布置的图像作为关联对进行存储。该成对数据可驱动前后对比滑块，允许用户还原，并且也是房源信息披露规则所要求的（第 4 步）。

做好应对差异的准备。 生成式输出存在随机差异，有时沙发可能并不合适。重新生成属于新任务，需要再扣除一张图片额度，因为 Roomagen 仅对渲染失败退款，不对用户不满意的结果退款。为每次重新运行分配独立的 Idempotency-Key，例如 photo-4821-stage-2：重复使用第一个键将返回原始任务，或者在请求体变更时返回 409。提供“重试”按钮，并确定这部分成本是由用户承担还是计入您的定价模型中。

设计等待和失败状态。 家居布置通常在 1 分钟内完成，在界面交互上属于较长等待。在上线前需设计好进度状态、失败状态（“渲染失败，已自动退款”）以及重试交互。

第 4 步：将披露构建到数据模型中

如果您的用户在房产广告中发布经过虚拟家居布置的照片，进行披露是他们的法定义务，而您的数据模型将决定这一流程是否轻松。Roomagen 的 API 不会添加披露标注，也不提供原图与修改后图片的绑定，且 Roomagen 的条款规定披露责任由用户承担，因此您的集成系统必须承载这些披露信息。

• 加州 AB 723 法案，自 2026年1月1日 起生效。 主管经纪人或销售人员（或其代理人）在房产出售广告中使用经过数字化修改的图像时，必须在图像上或紧邻图像处声明其经过修改，并添加链接、URL 或二维码，指向展示原始未修改图像的公开网站。加州房地产监管机构补充指出，当 AI 工具产生误导性广告时，责任“由持牌人及其主管经纪人承担，而非技术提供商”。
• 自 2027年1月1日 起的加州租房广告。 AB 2025 法案将类似的披露要求扩展到了租赁广告，涵盖住房提供方及其他主体，而不仅限于持牌人。
• MLS 规则在放置位置上存在分歧。 Canopy MLS 要求标注必须打在图像本身上，而不仅是在照片说明中；而 NWMLS 则不接受带有叠加图形或文字的照片。
• 面向欧盟的产品。 自 2026年8月2日 起，《欧盟人工智能法案》（EU AI Act）第 50 条要求生成或操纵“深度伪造”（deep fake）图像（与现有地点或物体相似、看似真实的内容）的 AI 系统部署者进行披露，对房产本身进行 AI 编辑的照片完全可能符合这一定义（详见我们的《欧盟人工智能法案》第 50 条指南）。

因此，请将披露信息存储为数据，而非直接写入像素：原图的公开 URL、带有使用工具和选项的 altered 标志，以及针对每个目标平台的披露文本与标注位置。在导出时渲染标注，而非在存储时固化。

这是面向开发者的总结，并非法律建议；我们的 AB 723 指南 和 MLS 照片要求指南 进行了更深入的探讨。

生产考量：速率限制、重试与额度预算

速率限制。 每个密钥在滑动 60 秒窗口内的限制为：POST /v1/jobs 每分钟 60 次请求，GET /v1/jobs/{id} 每分钟 300 次，GET /v1/tools 和 GET /v1/account 每分钟 120 次；此外，每个客户端 IP 每分钟 600 次，同一 NAT 地址后的所有服务器共享此额度。成功的响应带有 X-RateLimit-Limit 和 X-RateLimit-Remaining；429 rate_limited 响应则带有以秒为单位的 Retry-After，请严格遵守该值，切勿自行设计退避间隔。对于批量任务，请对提交进行队列排队：按每分钟 60 个任务计算，提交 500 张照片仅需 8 分钟多一点。

重试与错误代码。 每个错误都采用 { "error": { "code", "message", "doc_url" } } 格式。请根据 code 执行条件分支，切勿依赖 message：

失败经济学。 在生成过程中失败的任务会自动退款，但任务上的 images_charged 不会被重写，因此请将 GET /v1/account 作为余额的唯一可靠数据源。在对比各服务商时，除了单价外，还需审查其失败处理政策。

额度预算。 Roomagen 的 API 按图片计费，需预先在开发者门户购买套餐包：

套餐包永不过期且支持累加叠加。文档中记录的每种工具在 2K 渲染下每次消耗 1 张图片额度，在支持的工具上设置 resolution: "4K" 消耗翻倍，而家居布置始终消耗 1 张图片额度。在做预算时需将重新运行计入在内：例如一个平台每月布置 1,200 张照片，若预估十分之一的照片需要重做，则需要约 1,320 张图片额度，因此一份 Growth 套餐包可持续使用近两个月。

公开发布的价格差异较大（核对时间为 2026年10月）：ModelsLab 标价为每张室内渲染 $0.02，Decor8 所有 API 操作均为每张 $0.20，AI HomeDesign 年付按每张照片 $0.24、月付约每张 $0.49。除了单价，还需综合对比工具功能范围、Webhook 支持、失败策略及输出质量；我们的 虚拟家居布置 API 定价指南 和 家居布置 API 对比评测 逐一分析了各服务商。

关于成熟度的坦率说明。 Roomagen 的 API 相对年轻：第 1 版于 2026年8月30日 发布，采用单任务端点，其文档自 2026年10月3日 起才覆盖其支持的所有工具，因此它具备现代规范，但缺乏多年的公开运行记录。不兼容的重大变更（Breaking changes）在发布前会通过电子邮件通知持有有效密钥的账户；增量变更可能随时上线，因此请忽略您未识别的响应字段。

扩展集成：其他已收录工具

一旦家居布置闭环搭建完毕，实现“黄昏效果”或“消除杂物”按钮仅需更改 tool 和 options：

这些工具还支持 resolution（2K 或 4K）、tier（auto、guided 或 custom）以及 customPrompt（最多 500 个字符）。与家居布置不同，它们会忽略未知键（并在响应的 warnings 列表中列出），但仍会拒绝超出范围的值。对于无窗房间，向日景转黄昏传入 hasWindows: false，提示词即可略过窗户和室外景观指令。

GET /v1/tools 会返回您的密钥所能调用的所有标识符 slug 及其消耗的图片额度，且返回的每个 slug 均有完整文档。建议直接读取此列表而非硬编码，并请牢记 roomagen.com 上的工具名称并非 API 的 slug 标识符。

API 不支持的功能

• 不支持批量端点。 一个任务即通过一个工具处理单张图像；Web 应用中的批量处理功能不属于 API 的一部分，因此请在速率限制范围内对任务进行队列排队。
• 不提供披露标注。 输出结果不带披露标注或前后对比图。在账户购买套餐包之前渲染结果带有水印，购买后则不带任何 Roomagen 品牌标识。
• 不支持免费重新生成。 重新运行属于新任务，并按正常标准扣费。
• 不提供尺寸测量或 CAD 文件。 输出结果为 JPEG 图像，而非尺寸数据、矢量图或 DWG 文件。如果您需要通过照片获取房间测量尺寸，生成式图像 API 并不适合。
• 不保证输出完全准确。 生成式模型可能会产生瑕疵或不准确之处，因此在发布到房源之前请务必人工审核。
• 不包含仅限 Web 应用的功能。 修改、图片库和设计助手对话仅在 Roomagen 的 Web 应用中提供。

家居布置 API 集成中的常见错误

1. 阻塞请求线程。 在任务渲染期间一直保持用户请求连接，容易遭遇负载均衡器超时。应从您自己的 API 返回 202 Accepted，并通过推送方式向客户端更新状态。
2. 选项名称错误。 在家居布置任务中传入 room_type 或 resolution 会返回 invalid_request；家居布置要求使用其自有列表中的驼峰命名法键名，且 style 为必填项。
3. 仅仅依赖 Webhook。 在约 36 分钟的重试之后，Roomagen 将停止重试。如果没有对账调和机制，该任务将永久停留在“处理中”状态。
4. 签名验证方式错误。 对解析后的 JSON 进行哈希、遗漏时间戳前缀、使用 === 进行比较或跳过新鲜度检查，都会削弱验证的有效性。
5. Webhook URL 存在重定向。 纯 http 和私有主机会在最开始被拒绝并返回 webhook_url_rejected，且系统不会追踪重定向，因此末尾斜杠或 www 重定向会导致每次投递全部失败。
6. 使用随机幂等键或重新签名的 URL。 您没有存储的键将无法用于重放，从而导致重试再次扣费；在相同键下使用重新签名的 image_url 会返回 409。
7. 盗链结果 URL。 结果受服务商保留期限的限制。生成完成后请重新转存至自建存储。
8. 所有目标平台通用单一水印。 固化的 "Virtually Staged"（经过虚拟家居布置）标注可能会违反 MLS 禁止叠加文字的规则，且如果没有原图链接，其本身也无法满足 AB 723 法案的要求。

上线前检查清单

• API 密钥仅保存在您的服务器上，按环境分别配置。
• 家居布置请求始终携带 style，且不包含家居布置选项列表之外的任何字段。
• 每个任务都有从业务记录派生的 Idempotency-Key，且重试时重新发送原始请求体。
• Webhook 端点为最终的 https URL，基于原始请求体验证 v1= 签名，拒绝过期时间戳并在 10 秒内做出响应。
• 来自门户的 job.test 投递能够通过验证。
• 配置了对账调和机制，定时检查几分钟后仍处于处理中的任务。
• 重新转存结果，并将每张结果图与原图并列保存。
• 披露数据（原图 URL、修改标志、各平台适用标注）能够覆盖到每一个导出路径。
• 设置了读取 image_credits 的低余额告警，并将每个错误代码映射为向用户呈现的清晰提示。

核心结论：先打通闭环，再进行扩展

为应用程序添加虚拟家居布置是一项轻量级的集成工作：一个带有幂等键的 POST 请求、一个由对账机制兜底的带签名 Webhook 处理器，以及一个将原图与结果并存的存储环节。常规成功路径只需几十行代码；大部分工作集中在生产稳定性加固和披露数据处理上。这些设计均不绑定于单一供应商：异步提交、推拉结合的状态获取、重新转存结果以及原图/输出配对架构完全适用于任何家居布置 API。

若要基于此示例进行构建，请获取 Roomagen API 密钥：首个密钥包含 50 张免费图片额度，快速入门、Webhook 指南以及错误代码参考涵盖了所有技术细节。通过这一套集成闭环，您即可同时驱动虚拟家居布置、日景转黄昏照片编辑 & 转换、照片物体移除与物品清除、照片增强、虚拟翻新与改造以及平面图转3D等各项功能。