户型灯光助手 · 接入文档

快速开始

我们给你开通账户,交付一把 API Key 与初始余额(充值制)。
你的服务端判定用户是会员/非会员,调 POST /api/v2/sessions 拿到一个跳转 url。
把用户整页跳转到这个 url —— 接下来上传户型图、选场景、出图,全在我们页面完成。

你只需要对接一个接口(创建会话)。出图界面、上传、裁剪、下载都是我们的,你不用搭任何前端。

鉴权

创建会话用 Bearer Token,只在你的服务器后端调用:

Authorization: Bearer lp_live_xxxxxxxxxxxxxxxxxxxx

务必:API Key 是后端密钥,绝不要放进网页/App 前端,也不要拼进跳转链接。前端只会拿到我们签发的短时效会话 token —— 它本身也是一个「持有即可用」的凭证,分发方式见成本与安全。

创建会话

POST/api/v2/sessions

请求体

字段	类型	说明
`tier` 必填	string	`member`(会员,出 4 张)或 `non_member`(非会员,出 1 张)。
`end_user_id`	string	你侧的用户标识(透传,用于用量统计/对账)。
`ttl_hours`	number	会话有效期(小时),默认 6。
`max_renders`	number	本会话最多出图次数(0 = 有效期内不限)。用于按次控成本。

分清两个维度:tier 决定每次出几张(会员 4 / 非会员 1);max_renders 决定这条会话能出几次(不传 = 有效期内不限,不是一次性)。两者相互独立。
例:「会员、一天 5 次、每次 4 张」= tier=member + max_renders=5 + ttl_hours=24。我们不按自然日给每个用户记账,「按天」的额度由你那边给每个用户每天各发一条这样的会话来实现。

示例

最常见:会员、本会话最多出 5 次、每次 4 张、链接 24 小时有效。

curl -X POST {{BASE}}/api/v2/sessions \
  -H "Authorization: Bearer $LP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "member",
    "max_renders": 5,
    "ttl_hours": 24,
    "end_user_id": "u_8841"
  }'

非会员、单次体验(每次 1 张、出一次即失效):请求体换成 { "tier": "non_member", "max_renders": 1 }。

响应 200

{
  "session_token": "sess_xxxxx",
  "url": "{{BASE}}/app?s=sess_xxxxx",   // ← 把用户整页跳到这里
  "tier": "member",
  "max_scenes": 4,                      // 每次出几张(由 tier 决定)
  "expires_in": 86400                   // 链接有效期(秒)= ttl_hours × 3600
}

拿到 url 后,在你的页面做一次跳转(或 window.location = url)即可。会话 token 随机不可猜,但「不可猜」不等于「可公开分发」 —— 谁拿到这个 url,谁就能在有效期内用它出图(算你账)。务必为每个用户每次访问单独签发,详见下方成本与安全。

成本与安全

跳转 url 是「持有即可用」的临时出图凭证。token 明文挂在地址栏(/app?s=…),会随转发、浏览器历史、Referer、截图、群里贴链接外泄。任何拿到此链接的人,都能在 ttl_hours / max_renders 限额内出图,全部计入你的账单、直接消耗你的预付余额 —— 我们不做用户 / IP / 设备绑定校验。

你仅有的两道成本兜底:`ttl_hours` 与 `max_renders`

每个用户、每次访问单独签发会话,切勿复用或公开张贴同一条链接。
ttl_hours 设尽量短;max_renders 按需收紧 —— 不传 = 有效期内不限次,链接一旦外泄即可被刷满你的余额。非会员单次体验建议 max_renders=1。
end_user_id 只是对账标签,不做任何限额、也不绑定 / 鉴权用户 —— 传了它系统也不会自动「按用户卡量」。要按用户控量,只能靠「每个用户单独签发 + 设 max_renders」。
同一条会话可被多设备 / 多人并发使用;max_renders 是尽力上限,高并发下可能被略微突破(实际交付可比设定值多几张),请按此预留余量、勿当精确硬闸。

账户级硬闸(可选):每日花费上限。若担心 Key 泄漏或链接被滥用一天烧光余额,我们可在开户时为你账户配一个每日花费上限(按北京自然日累计已交付张数)。命中后该账户当日出图返回 402 daily_spend_cap_reached —— 注意这不是余额不足、充值解不开,需联系对接人上调或等次日北京时间 0 点重置。默认不设(只受预付余额约束),需要就找对接人开。

用户体验(都在我们页面)

用户看到什么

跳进来后直接是出图工具:上传单空间户型图 → 自动/手动框选房间 → 选空间/风格/场景 → 生成 → 确认基础图 → 出灯光场景图 → 下载。

无需登录、无口令;会员可选最多 4 个场景,非会员 1 个,由会话自动控制。

你不用管的

界面、上传、裁剪、出图、下载、合规标识 —— 全是我们的。你只负责判定会员/非会员并签发会话。

计费

预付 · 按张计费

账户是预付余额。会员一次最多出 4 张、非会员 1 张,每产出一张已交付的图扣一次单价。余额不足时该用户无法继续出图,充值后恢复。

只为「拿得到的图」付费

「失败」= 技术性没出图(模型未返回 / 图床拿不到图片地址,系统自动判定)—— 只有这种才不计费、自动退回余额。只要图成功产出(拿到地址)就计费,与终端用户「觉得像不像、满意不满意」无关。一次出图里部分场景技术失败,只按实际出成的张数计费。

会员单实际计费 1~4 张(浮动,属正常)。我们的页面是两段式:用户先看到 1 张基础图并在「这是你的房间吗?」处确认,确认后才生成其余场景。所以会员单实际张数 = 1 张(用户停在基础图 / 未点确认就离开)~ 4 张(走完全部场景),再扣掉技术失败的张 —— 一律以 /api/v2/usage 逐张交付明细为准,不是少出图的故障。

预留(held):交付前余额就会下降。提交 / 确认出图时,系统先按本次预估张数冻结金额 —— balance_cents 立即下降、held_cents 等额上升;每交付一张转为实扣,未交付 / 技术失败的部分终态自动退回 balance_cents。因此出图中轮询 /api/v2/account 看到余额下降、held_cents 上升属正常,不是提前扣费;部分失败后余额回升也属正常。

会员低余额会中途断在基础图。会员单分两段预留:提交时只按 1 张基础图预留,确认时再按其余场景预留。若余额只够出基础图 —— 基础图照常生成并实扣(已交付不退),但用户点「确认」续出其余场景时会因余额不足返回 402 insufficient_balance,任务停在基础图态。由于你零前端,终端用户会在我们出图页直接看到该提示。请预留足够覆盖会员满额(4 张)的余额;充值后用户可在会话有效期内重新点确认续出。

会员 / 非会员的判定完全由你决定 —— 我们只按你在 tier 里声明的级别给对应张数,并按你账户的总用量结算。

账户 / 用量(对账)

金额字段单位均为「分」(1 元 = 100 分) —— 对账时除以 100。你的单价以双方约定为准,程序里读 GET /api/v2/account 的 price_per_image_cents 即可(held_cents 含义见计费)。

GET/api/v2/account Authorization: Bearer

{ "balance_cents": 200000, "held_cents": 0, "price_per_image_cents": <你的单价>, "status": "active", "timezone": "Asia/Shanghai" }

GET/api/v2/usage?from=2026-06-01&to=2026-06-30&end_user_id=&cursor=&limit=1000

按北京时区拉取已交付出图明细(一张图一行,含 end_user_id),用于你侧对账。next_cursor 非空时继续翻页。

{ "events": [ {"render_id":"..","end_user_id":"u_8841","scene":"明亮","unit_price_cents":<你的单价>,
    "image_url":"https://..","ts":1781990000,"beijing_date":"2026-06-20"} ],
  "next_cursor": null, "timezone": "Asia/Shanghai" }

把这两个接口接进你自己的后台,你和财务即可随时核对用量与账单。我们按消费月度开票。

回调 Webhook(可选)

如果你想在用户出图完成时收到通知(比如更新你侧的用量看板),可以登记一个回调 URL(必须 https、公网可达)。每个 render 进展到 done / failed 等状态时,我们 POST 给你:

X-LightPlan-Signature: <hex>   X-LightPlan-Timestamp: 1781990000

{ "render_id":"..","account_id":"acct_..","status":"done",
  "images":[{"scene":"明亮","url":"https://.."}], "error":"", "created_ts":1781990000 }

验签:HMAC-SHA256(secret, "{timestamp}.{原始请求体}"),用我们给的 secret 校验,并拒绝早于 5 分钟的重放。回调是尽力投递,以 /api/v2/usage 为对账真相源。

错误码

错误统一返回 {"error":"<机器可读码>"} + HTTP 状态:

HTTP	error	含义
400	`invalid_tier`	tier 不是 member / non_member
401	`invalid_api_key` / `invalid_session`	Key 无效 / 会话无效或过期
402	`insufficient_balance`	余额不足 → 充值
402	`daily_spend_cap_reached`	触及账户每日花费上限(与余额无关,充值无效)→ 联系对接人上调上限或等次日北京时间 0 点重置
403	`account_closed`	账户已关停 —— 你调 `POST /api/v2/sessions` 收到的 403 是这个码
403	`account_suspended`	账户被暂停;此时 `/sessions` 仍正常返回 200,该码只在用户随后于我们页面出图时触发(不在你的 `/sessions` 响应里)。请以 `GET /api/v2/account` 的 `status` 判断账户健康度
422	`image_rejected`	户型图不合格(太暗/太小/无法识别)
429	`session_render_limit` / `rate_limited`	会话出图次数用尽 / 请求过快

FAQ

会员/非会员怎么区分?

由你判定。创建会话时传 tier=member(4 张)或 non_member(1 张)即可,我们不介入你的会员体系。

一个会话能出几次图?

默认在有效期(ttl_hours)内不限次数;想按次控成本,传 max_renders。每张交付的图都计费。

怎么先联调不花钱?

我们给你一把沙箱 Key:返回占位图、$0 不计费,流程与生产一致,联调通过后换生产 Key。

用户上传的图有什么要求?

单个空间的局部图(裁好的一个房间),白底清晰、短边 ≥ 600px。我们页面带框选工具帮用户从整套图里裁出一个房间。