Spacevo 室内设计 API 文档

Spacevo 室内设计 / 虚拟软装 API（v1）的鉴权、端点、参数、错误码与限流说明。

Spacevo API 跑的是和网页端完全一样的出图管线，只是把浏览器那一层拿掉了。一个 POST 提交房间照片，一个 GET 取回无水印原图。

想先看价格和适用场景？请看 API 介绍页。

Base URL

https://spacevo.io/api/v1

所有端点收发 application/json，只走 HTTPS，明文 HTTP 请求会被拒绝。

鉴权

每个请求都要带 Bearer key：

Authorization: Bearer sk-your_key

账号开通 API Plan 后，在 Settings → API Keys 创建和吊销 key。key 形如 sk- 加 32 位字符，只在创建时完整显示一次，请存进密钥管理服务，不要提交进代码仓库。
key 只发给 API Plan 付费用户，没有免费 API 额度；想先验证效果，请用网页端。
key 缺失、格式不对、不存在、已吊销，一律返回 401；所有失败情形返回的 401 完全一样，无法用来试探哪把 key 存在。
鉴权和额度是两道独立的门：key 有效但账号没有 API 额度时，鉴权能过，出图时返回 402。

key 等同于账号凭据。绝不要下发到浏览器、移动端或任何你控制不了的客户端，请求一律从你自己的服务端发起。

额度与计量

1 张图 = 1 个额度。额度在渲染任务被受理时扣，不是出图完成时扣。
API Plan 每个自然计费月发放 1,000 张。额度在每个计费月初重置， 不滚存到下个月。
API 额度与网页端积分是两个池子：订阅赠送的积分、积分包、注册送的 5 个积分都属于浏览器产品，API 不会动它们，反过来也一样。
我方原因导致的出图失败会自动把额度退回 API 池。
两个端点都会返回 credits_remaining，按你自己的阈值告警即可，不必等到吃 402。

限流

每个 key 每分钟 60 次请求，提交端点和轮询端点各自一个独立窗口——轮询在跑的任务不会吃掉你提交新任务的额度。

超限返回 429，响应头 Retry-After 给出需要等待的秒数。请退避重试；几百张的批量任务建议匀速提交，不要一次打满。

POST /api/v1/render

提交房间照片、发起一次渲染。这个调用立即返回，不会等图出完。

请求体

字段	类型	必填	说明
`image_url`	string	是	原图的公网 HTTPS 地址，最长 2,048 字符。出图期间该地址必须无需鉴权即可访问；解析到内网或回环地址的域名会被拒绝。
`style`	string	是	二选一：Spacevo 风格库的 id——`scandinavian`、`modern`、`japandi`、`industrial`、`minimalist`、`bohemian`、`midcentury`、`luxury`、`newchinese`、`cream`、`french`、`mediterranean`；或 3–500 字的自由描述文本（会走内容审核）。
`room_type`	string	否	`living-room`（默认）、`bedroom`、`kitchen`、`dining-room`、`bathroom`、`home-office`、`kids-room`、`villa`。
`mode`	string	否	`restyle`（默认）给已有家具的房间换风格；`staging` 给空房补家具。v1 只接受这两个值。

示例

curl -X POST https://spacevo.io/api/v1/render \
  -H "Authorization: Bearer sk-your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.example.com/listings/8412/living-room.jpg",
    "style": "scandinavian",
    "room_type": "living-room",
    "mode": "staging"
  }'

响应 — `202`

{
  "id": "8f4c1d6e-2b7a-4f19-9c3d-5a10e7b64f28",
  "status": "processing",
  "credits_remaining": 962
}

请把 id 存下来，它是一个 UUID，也是这次渲染唯一的句柄。

GET `/api/v1/render/{id}`

查询一次渲染的当前状态，轮询到终态为止。

curl https://spacevo.io/api/v1/render/8f4c1d6e-2b7a-4f19-9c3d-5a10e7b64f28 \
  -H "Authorization: Bearer sk-your_key"

响应 — `200`

{
  "id": "8f4c1d6e-2b7a-4f19-9c3d-5a10e7b64f28",
  "status": "succeeded",
  "image_url": "https://cdn.spacevo.io/interior/api/8f4c1d6e.jpg",
  "credits_remaining": 962,
  "created_at": "2026-08-06T09:14:22.481Z"
}

`status`	含义
`processing`	已受理，出图中——任务刚创建时也是这个状态。
`succeeded`	完成，`image_url` 可用。
`failed`	出图失败，额度已退回，`error` 字段说明原因。

image_url 只在 succeeded 时出现，error 只在 failed 时出现；id、 status、credits_remaining、created_at 每次都返回。id 不存在、属于别的账号、或那次出图是在网页端做的，一律返回 404。

image_url 是无水印原图。请下载后存到你自己的存储，这个地址不是长期图床。

正常负载下几十秒出图。建议每 2–3 秒轮询一次，轮得更快只会更快吃掉限流额度。

错误码

错误统一返回 JSON：

{
  "error": {
    "code": "insufficient_quota",
    "message": "Your API quota for this period is exhausted. Upgrade or wait for the next billing period."
  }
}

HTTP	code	发生了什么	怎么处理
`401`	`unauthorized`	key 缺失 / 格式错 / 不存在 / 已吊销。	检查 `Authorization` 头，以及 Settings → API Keys 里这把 key 的状态。
`402`	`insufficient_quota`	本计费周期的额度用完了。	等下个月重置，或联系我们提档。额度不滚存。
`404`	`not_found`	渲染 id 不存在；别的账号的 id、网页端做的出图，也返回这个。	核对 `POST` 返回时存下来的 id。
`422`	`invalid_request`	请求体不是 JSON、参数缺失、取值不在枚举内，或 `image_url` 不是可访问的公网 HTTPS 地址。	按 `message` 指出的字段改完重提。这种情况不扣额度。
`429`	`rate_limited`	这把 key 在这个端点上一分钟内超过 60 次请求。	按 `Retry-After` 给的秒数退避后重试。不扣额度。
`451`	`content_rejected`	自由文本的 `style` 被内容审核拦下；内置风格 id 不走审核。	不要用同样的文本重试。不扣额度——审核发生在扣费之前。
`503`	`moderation_unavailable`	内容审核服务不可用，请求按「审核不通过」处理。	稍后重试。不扣额度。
`500`	`internal_error`	我们这边出问题了。	退避后重试。不扣额度。

5xx 表示问题在我们这边：请退避重试，且不扣额度。

完整示例

import os
import time

import requests

API = "https://spacevo.io/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SPACEVO_API_KEY']}"}

created = requests.post(
    f"{API}/render",
    headers=HEADERS,
    json={
        "image_url": "https://cdn.example.com/listings/8412/living-room.jpg",
        "style": "scandinavian",
        "room_type": "living-room",
    },
    timeout=30,
).json()

while True:
    render = requests.get(
        f"{API}/render/{created['id']}", headers=HEADERS, timeout=30
    ).json()
    if render["status"] in ("succeeded", "failed"):
        break
    time.sleep(2)

print(render["image_url"])

const API = 'https://spacevo.io/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.SPACEVO_API_KEY}`,
  'Content-Type': 'application/json',
};

const created = await fetch(`${API}/render`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image_url: 'https://cdn.example.com/listings/8412/living-room.jpg',
    style: 'scandinavian',
    room_type: 'living-room',
  }),
}).then((res) => res.json());

let render;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  render = await fetch(`${API}/render/${created.id}`, { headers }).then((res) =>
    res.json()
  );
} while (render.status === 'processing');

console.log(render.image_url);

出图的使用

API Plan 自带商用授权：生成的图可以直接上房源门户、宣传册和对客产品。有一条规矩到哪都适用——多数房产平台和行业规范要求虚拟软装图必须标注为虚拟软装，请按你所在市场的要求写上说明。

v1 不含视频渲染。需要视频，或者量级超出套餐？联系我们。

Spacevo 室内设计 API 文档

On this page