如何为你的应用添加虚拟软装：开发者API教程

你要构建什么：软装功能的架构

学完本教程，你的应用将能够接收用户上传的房间照片，发送给虚拟软装API，并在10–40秒后返回一个摆好家具、照片级真实的房间版本。这就是整个功能。其余一切——Webhook、重试、积分预算、披露标签——都是为了让这个闭环在生产规模下可靠运转。

需求端已经非常成熟。全球虚拟软装市场在2025年达到4.54亿美元，随着房源在线上争夺注意力，软装需求持续攀升：

"全球虚拟软装解决方案市场预计将从2025年的4.54亿美元增长到2035年的47.3亿美元。"——Business Research Insights

如果你运营的是房源平台、摄影交付工具、物业管理仪表盘或地产科技CRM，软装正日益成为用户期望在你的产品内部直接使用的功能，而不是要跳出去访问的独立服务。

在架构上，市面上的每一个软装API——Roomagen、AI HomeDesign、Decor8以及其他几家——都遵循同样的异步任务模式。生成需要几十秒，远超HTTP请求可以保持打开的时长，所以流程永远是：提交任务，立即拿到任务ID，稍后接收结果。

阶段	处理方	典型延迟
上传并校验照片	你的应用	1秒以内
提交软装任务	你的后端 → 软装API	1秒以内
AI生成	软装服务商	10–40秒
完成通知	Webhook（推送）或轮询（拉取）	0–10秒
存储并展示结果	你的应用	1秒以内

本教程以Roomagen API为实操示例，因为它的端点能干净地映射到这个通用模式，但这里的每个概念——异步任务、Webhook与轮询、幂等性、失败经济学——都可以直接迁移到任何服务商。凡是Roomagen特有的行为，文中都会明确指出。

开始之前：密钥、环境与图片要求

写集成代码之前你需要三样东西：一个API密钥、一套隔离环境的方案，以及满足服务商输入要求的图片。

获取密钥。 Roomagen的API处于早期访问阶段：在roomagen.com/api加入候补名单，免费开发者档每月包含50次带水印调用——足够在花一分钱之前构建并测试完整集成。密钥形如 rmg_live_...，通过 X-Api-Key 请求头发送。无论选择哪家服务商，同样的两条规则都适用：把密钥放在服务器端环境变量里，绝不要把它打进客户端JavaScript或移动端二进制包——任何人都能从中提取密钥并耗尽你的积分。

环境。 如果服务商支持，为开发和生产使用不同的密钥。开发期间，带水印的输出其实是好事——它能防止测试图片意外流入真实房源。

图片输入。 软装质量高度依赖输入质量。下表以Roomagen的要求为具体案例，总结了软装API的典型输入期望。

要求	建议
格式	JPEG或PNG
传递方式	公开的 image_url（推荐）或 image_base64
分辨率	长边1024px以上；输入越高，输出质量越好
内容	单个房间、水平拍摄、光线适中；广角可用
房间状态	空房间的软装效果最可预测；已布置房间更适合重新设计类工具

一条实用提示：对于超过极小体积的文件，传URL优于base64。你的后端省去了重新编码的开销，请求体保持小巧，服务商直接从你的CDN或签名存储URL拉取图片。

最后，用程序化方式检查积分余额。Roomagen提供 GET /api/v1/account，返回 image_credits——从管理后台或每日cron轮询它，就不会在月中被打个措手不及。多数积分制服务商都提供等价端点，现在花十分钟接一个低余额告警，胜过日后的服务中断。

第一步：提交软装任务

核心调用就是一个POST。你指定要运行的工具、图片、样式选项，以及可选的完成通知Webhook URL。

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.yourapp.com/rooms/123.jpg",
    "options": { "room_type": "living_room", "style": "scandinavian" },
    "webhook_url": "https://yourapp.com/hooks/roomagen"
  }'

响应会立即返回——早于生成完成：

{ "job_id": "job_8f3ka92m", "status": "processing", "images_charged": 1 }

在Node.js后端发起同样的调用：

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"
  },
  body: JSON.stringify({
    tool: "virtual-staging",
    image_url: imageUrl,
    options: { room_type: "living_room", style: "scandinavian" },
    webhook_url: "https://yourapp.com/hooks/roomagen"
  })
});
const { job_id } = await res.json();

响应到达的那一刻要做两件事。第一，先把 job_id 持久化到你自己的记录上——房源、照片、用户——再做其他任何事。这行记录是你的幂等锚点：进程崩溃时，你可以按ID恢复任务，而不是重新提交并付两次钱。第二，记录 images_charged，让你的内部账目与服务商保持一致。

注意 tool 只是一个slug。Roomagen的 GET /api/v1/tools 端点列出了40+个工具，全部使用完全相同的任务模式——包括用于空房间的虚拟软装、日转夜黄昏转换、用于除杂的物品移除、用于曝光和色彩校正的图像增强、草图转户型图转换，以及虚拟翻新。一旦下面的任务闭环对软装跑通了，给你的应用加一个"黄昏照片"或"移除杂物"按钮就只是改一行 tool 字段的事。这种多工具模式值得在你评估的任何服务商那里确认：单工具API意味着路线图扩张时要从头重新集成。

具体到空房房源，virtual-staging 是主力工具，而已布置的房间更适合先走重新设计工具或清空家具工具——这个区别在你的UI里可以做成一个简单的"房间是空的吗？"开关。

第二步：处理任务完成——Webhook还是轮询

任务正在处理中。现在你需要知道它何时完成。机制正好有两种，成熟的集成两种都用。

维度	Webhook（推送）	轮询（拉取）
延迟	完成时近乎即时	最多一个轮询间隔（5–10秒）
基础设施	需要公开的HTTPS端点	除调度器外无需其他
可靠性	投递可能失败（你的宕机、网络）	稳健——循环由你掌控
安全工作	需要签名验证	仅API密钥
服务器成本	每任务一个请求	每任务N个请求
适用场景	量级生产	开发、兜底、低量

推荐模式：Webhook为主通道，轮询做兜底。 为每个任务注册 webhook_url，同时安排一个轮询检查——每5–10秒调用一次 GET /api/v1/jobs/{id}——如果比如60秒内没有Webhook到达就激活。轮询设置一个硬超时上限（2–3分钟），超过后在你的UI里把任务标记为失败。这套组合在双方任何一侧的Webhook故障中都能存活，且几乎不增加成本。GitHub和Stripe的Webhook指南收敛于同样的原则：快速响应、验证签名、去重，并用轮询做对账。

一个带签名验证的最小Express Webhook处理器：

app.post("/hooks/roomagen", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.get("X-Roomagen-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.ROOMAGEN_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { job_id, status, result_urls } = JSON.parse(req.body);
  completeJob(job_id, status, result_urls); // must be idempotent
  res.sendStatus(200);
});

这里有三个要点。第一，在原始请求体上验证签名，在JSON解析之前——Roomagen用HMAC-SHA256（RFC 2104）对载荷签名，并把摘要放在 X-Roomagen-Signature 中；多数服务商使用等价方案。跳过验证意味着任何发现你端点URL的人都能向你的应用注入伪造的"已完成"事件。第二，使用时序安全的比较，而不是 ===。第三，让完成处理器幂等：Webhook系统失败会重试，同一事件可能到达两次，轮询也可能已经先完成了任务。一个 UPDATE ... WHERE status = 'processing' 守卫通常就够了。

轮询时，状态端点返回你需要的一切：status（processing、completed 或 failed）、成功时的 result_urls、失败时的 error，以及值得记录用于延迟监控的 processing_ms。

第三步：向用户交付结果

完成的任务返回 result_urls——一个指向生成图片的URL数组。抵制直接热链它们的诱惑。

把结果转存到你自己的存储。 下载每个结果URL并写入你自己的S3、R2或GCS存储桶，然后通过你的CDN提供服务。服务商的结果URL应被视为临时交付机制，而非永久基础设施：保留策略各不相同，如果服务商清理旧任务或你更换供应商，你产品里的图片不应该因此挂掉。下载转存这一步只有五行代码，却消除了未来一整类事故。

永远保留原图。 把源照片和软装照片作为关联对存储。这很重要，原因有三：你的UI可以提供前后对比滑块（一直是展示软装效果参与度最高的方式），你的用户可以还原，而且——在美国房地产语境下——法规越来越要求未编辑的图片保持可用。Roomagen的任务结果正是为此设计为原图与编辑图配对返回。

在房源场景中为软装图片打标签。 如果你的用户会发布到MLS平台，披露不再是可选的礼节。加州的AB 723自2026年1月1日起要求披露AI修改的房源图片，全美的MLS规则都期望可见的"Virtually Staged"标签。Roomagen提供可选的披露标签参数，把标记直接渲染到输出图片上，这是让下游发布保持合规的最省力方式。法律细节是另一个独立话题——对你的集成来说，简短版本是：在数据模型中存储软装/原图的区分，并在软装图片可能触达房源的任何地方展示标签。

提供重新生成入口。 生成式输出有随机性；有时沙发就是不对。Roomagen为每张图片包含1次免费重新生成，所以在每个结果旁边放一个"重新生成"按钮，第一次重试不花你一分钱，还能大幅减少客服工单。无论用哪家服务商，确认其重新生成政策并在UI中如实映射，而不是让用户为掷硬币买单。

同一条交付管线可以服务你以后添加的所有其他工具——从草图生成的户型图、黄昏外景、天空替换或厨房翻新预览，都会通过完全相同的Webhook以 result_urls 的形式返回。

生产环境考量：速率限制、重试与积分预算

上面的集成已经能跑。以下四条实践让它在负载下继续跑。

重试与退避。 把任务提交收到的 429 和 5xx 响应视为可重试，采用指数退避（1秒、2秒、4秒，上限30秒）。关键是，只在确定任务未被创建时才重试——如果提交是在请求发出后超时的，先检查你的存储记录和账户的任务列表再重新提交，否则你会为重复生成付费。这正是第一步里的幂等锚点在发挥作用。

失败经济学。 在为利润建模之前先弄清失败的成本。在Roomagen上，基础设施失败永不消耗积分，失败任务自动退款，所以 failed 状态只是不便，不是成本。并非每家服务商都这样——有些按尝试次数收费——所以这一项应该和单张价格一起列入你的评估清单。你的UI应当区分"失败了，未扣费，再试一次"和"完成了但不合口味，用你的免费重新生成"。

积分预算。 积分包API奖励量级承诺。Roomagen当前的积分包：

月度量级	包价	实际单张成本
500张	$125	$0.25
2,500张	$550	$0.22
10,000张	$2,000	$0.20
50,000+张	定制	协商

作为对比，AI HomeDesign的API约为每张$0.24，Decor8约为**$0.20**——可信的服务商聚集在同一价格带，所以服务商选择往往取决于工具广度、Webhook质量和合规特性，而不是几美分的单价差。做预算时，把预期量级乘以约1.1倍以覆盖免费额度之外的重新生成和用户试错；同时记住买方视角的利润数学：经纪人为人工软装服务通常支付每张$16–$69，所以一个成本仅$0.20–$0.25/张的功能，无论你怎么打包定价都有健康的空间。

关于成熟度的坦诚提醒。 Roomagen的API是2026年的新入局者，目前处于候补名单制早期访问——你得到的是现代化的工程体验（HMAC Webhook、自动退款、单端点40+工具），但没有十年久经考验的可用性历史或庞大的公开社区。如果你今天就需要即时自助注册，上面提到的替代方案卖API的时间更长。本教程的通用架构正是为此刻意做到服务商可移植：你的任务表、Webhook处理器和存储管线在更换供应商时几乎不需要改动。

软装API集成中的常见错误

七种失败模式在软装集成中反复出现。全部可以避免。

1. 阻塞请求线程。 为10–40秒的生成保持用户HTTP请求打开会占用服务器资源，并在多数负载均衡器上超时。提交任务，返回带你内部记录ID的 202 Accepted，让客户端通过WebSocket、SSE或对你自己API的简单轮询订阅更新。

2. 只信Webhook。 你的部署窗口、一次TLS配置错误或服务商侧的投递抖动，迟早会吞掉一个Webhook。没有轮询兜底，那个任务就会在你的UI里永远卡在"处理中"。第二步的双通道模式几乎零成本。

3. 跳过签名验证。 未验证的Webhook端点等于向你的应用状态开放的写入API。在原始请求体上用时序安全比较验证HMAC——就十行代码，上文已给出。

4. 热链结果URL。 服务商的URL是临时的。完成时把结果转存到你自己的存储，每一次都要。

5. 不做幂等检查就重新提交。 网络超时加上天真的重试等于重复扣费。提交时立即持久化 job_id，重试要以你自己的记录为门槛。

6. 在房源市场忽视披露。 如果软装图片能通过你的产品到达MLS，一张无标签的图片在加州已是用户的法律风险，在主要门户上则是政策违规。在数据模型中携带软装标志并渲染标签。

7. 不设计失败体验就上线。 10–40秒在UI语境里很漫长，而且一小部分任务必然失败。在上线前——而不是第一张客服工单之后——设计好处理中状态（进度指示、骨架图）、失败状态（清晰的重试入口、"未向你扣费"）和重新生成入口。

结论：先上线核心闭环，再扩展

给应用添加虚拟软装真的是个小集成：一个创建任务的POST、一个带轮询兜底的Webhook处理器，加一个结果存储步骤。可用原型一个下午就能搞定；生产加固——幂等的完成处理、签名验证、重试纪律、披露标签——再加一天。量级包每张$0.20–$0.25、失败任务自动退款、结果10–40秒送达——这套经济学从摄影师的交付门户到全国性房源平台都成立。

这套架构刻意保持服务商中立：异步任务提交、双通道完成处理、结果转存，以及数据模型中的软装/原图配对，适配你现在选择或将来迁移到的任何软装API。

如果你想基于本教程的实操示例开始构建，加入Roomagen API候补名单——免费开发者档每月包含50次带水印调用，足以在零付费承诺下覆盖本指南的完整集成与测试周期。此后，同一个任务端点在单次集成背后为你提供虚拟软装、日转夜、物品移除、图像增强和户型图工具。