Stagify.ai › API 文档

Stagify API

API 控制台

用你自己的代码为房产照片做虚拟布置。一次 HTTP 调用返回一张布置好的图片。预付额度每张 0.15 美元，无订阅、无最低消费，也不会出现失控的账单。

基础 URL: https://stagify.ai/api/v1
身份验证: Bearer stg_live_…
内容类型: multipart/form-data

简介

这个 API 只暴露一件事：网页应用背后的虚拟布置流水线。你上传一张房间照片，指定房间类型和家具风格，就能在同一个响应里拿到布置好的图片。没有任务队列，正常路径上也没有需要轮询的东西。

额度以整张图片计。你预先购买，每次渲染成功扣一张。渲染失败会自动退还，所以你只为真正拿到的照片付费。而且由于余额是预付的，密钥被盗最多损失余额本身。月底不会有账单。

密钥仅供服务器到服务器使用。API 不发送 CORS 头，浏览器无法直接调用；这是刻意为之，能从浏览器 JavaScript 触及的密钥就是已泄露的密钥。密钥只显示一次，我们只保存哈希，吊销立即生效。

快速开始

在你的API 密钥页面创建密钥，购买额度包，然后上传一张照片。响应中会以 data URL 形式返回布置好的图片。

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

一次渲染最长需要几分钟。请把客户端读取超时设为 300 秒，并使用相同的 Idempotency-Key 重试。正是这一点保证同一张照片绝不会被扣两次费。

额度包

正在加载价格…

请求参数

POST /api/v1/renders，以 multipart/form-data 发送。下表中所有可接受的值也由 GET /api/v1/options 以 JSON 提供，该接口无需 API 密钥，客户端可以据此填充自己的下拉列表，而不必把本表硬编码进代码。

字段	类型	说明
`image`	file	必填。房间照片。JPEG、PNG 或 WebP，最大 25 MB。校验的是 MIME 类型，而非文件扩展名。
`roomType`	enum	`Bedroom`、`Living room`、`Dining room`、`Kitchen`、`Office`、`Bathroom`、`Outdoors`、`Dorm`。默认 `Living room`。区分大小写和空格，且无法识别的值不会被拒绝，而是作为自由文本写入提示词，所以 `Living Room` 不等于 `Living room`。
`furnitureStyle`	enum	`standard`、`modern`、`midcentury`、`scandinavian`、`luxury`、`coastal`、`farmhouse`、`custom`。默认 `standard`，无法识别的值也会静默变成它。`custom` 会用你的 `additionalPrompt` 取代内置的风格文本。
`additionalPrompt`	string	针对本次渲染的自由文本说明。
`removeFurniture`	boolean	布置前先清空房间。请发送 `true` 或 `on`；其他任何值，包括 `1` 和 `yes`，都视为假。
`keepFurniture`	string	用自由文本说明要保留什么，例如 `keep the dining table and the built-in shelves`。仅在 `removeFurniture` 开启时才读取。500 个字符。
`furnitureImage`	file[]	最多 5 张家具参考照片。格式与大小限制同 `image`。
`labelVirtuallyStaged`	boolean	在输出图片上烧录“Virtually staged”声明。
`stampStyle`	enum	`dark`、`light`、`minimal`、`banner`。默认 `dark`。不区分大小写；无法识别的值回退为默认值。
`stampScale`	number	`0.7` 到 `1.6`，默认 `1`。超出范围的值会被夹到边界，而不是被拒绝。
`stampLang`	enum	标记语言：`english`、`spanish`、`french`、`german`、`chinese`、`korean`、`portuguese`、`russian`、`italian`、`japanese`、`dutch`。默认 `english`。
`variations`	integer	只接受 `1`。需要更多请发起并发请求。

幂等性

一次渲染会占用连接数分钟，因此真正会咬到你的故障是：工作已经完成之后连接断开, 费用已扣，手里却什么都没有。请在每个请求上发送 Idempotency-Key 头，并用相同的值重试。

我们这边的记录	重试会发生什么
一个成功的请求，参数相同	返回已保存的结果，并带上 `X-Stagify-Replayed: true`。不会二次扣费。
一个仍在执行的请求	`409 REQUEST_IN_FLIGHT`。稍候再试。
渲染中途被放弃的请求	在已有扣费上重新执行，最多三次。
同一个密钥配上不同参数	`422 IDEMPOTENCY_KEY_REUSED`。请换一个新的键。

省略该头是允许的，代表没有重放保护，这是诚实的默认行为。我们不会从你的照片派生键：同一房间两次真正独立的渲染会互相冲突，第二个调用方会拿到第一个的图片。

虚拟布置声明

许多 MLS 与 NAR 规则要求虚拟布置过的照片必须注明。labelVirtuallyStaged 会把该声明烧录进像素，而不是作为下游工具可以剥离的元数据附加。

如果声明无法添加，图片会被扣下而不是不加标注地交付，调用返回 500 DISCLOSURE_STAMP_FAILED，并退还你的额度。该行为无法关闭，也没有任何按密钥的默认设置能悄悄停用它。

错误

所有失败都返回 { "error": "…", "code": "…" }。请依据 code 分支，切勿依据消息文本。消息会变，代码不会。

状态码	错误码	如何处理
401	`API_KEY_MISSING` / `API_KEY_INVALID` / `API_KEY_REVOKED`	检查 `Authorization` 头，或者重新创建一个密钥。
402	`INSUFFICIENT_CREDITS`	请充值。响应体中带有 `credits_remaining`。
403	`ACCOUNT_SUSPENDED`	请联系客服。
400	`VARIATIONS_UNSUPPORTED`	本 API 每个请求渲染一张图片。请改用并发请求。
409	`REQUEST_IN_FLIGHT`	该幂等键仍在执行。稍候再试。
409	`CONCURRENCY_LIMIT`	同时渲染的数量过多。几秒后重试。
422	`IDEMPOTENCY_KEY_REUSED`	你用同一个键配了不同参数。请换一个新的。
422	`NO_IMAGE_GENERATED`	模型没有返回内容。已退款；请重试或换一张照片。
429	`RATE_LIMITED`	请降低频率后重试。
500	`DISCLOSURE_STAMP_FAILED`	声明无法添加，图片已被扣下。已退款。
500	`RENDER_FAILED`	已退款。联系客服时请提供 `ref`。

其他接口

GET /api/v1/options：上面每个枚举的可接受值。无需 API 密钥。
GET /api/v1/me：我的密钥能用吗？返回账户与余额。
GET /api/v1/credits：余额与累计数据。
GET /api/v1/renders/{id}：某次渲染的状态。

每个响应都带有 X-Stagify-Credits-Remaining，无需轮询即可看到余额下降。

有疑问、需要更高配额，或希望开票而非刷卡：team@stagify.ai。