接入文档

快速开始

1. 到 自助接入大厅 领沙箱 Key 免费联调;或由我们开通账户,交付 API Key 与初始余额(充值制)。
2. 你的服务端决定给这个用户多少额度(几张图、几条视频),调 POST /api/v2/sessions 拿到一个跳转 url。
3. 把用户整页跳转到这个 url —— 上传户型图、出图、下载,全在我们页面完成。

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

鉴权

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

Authorization: Bearer lp_live_xxxxxxxxxxxxxxxxxxxx

创建会话

一次签发就是一张限额卡:图几张、视频几条、多久有效。规则只有一条 —— 额度写多少用多少,0 或不传 = 不能;没有「不限」(链接谁拿到谁能用, 不限量等于把你的预付余额挂在网上)。

请求体

示例

总共 20 张、链接 24 小时有效:

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

单张体验:{ "max_images": 1 }。
再允许出 1 条联动视频:加上 "max_videos": 1(记得图至少给 2 张 —— 一条片要两个已出的场景才串得起来)。

响应 200

{
  "session_token": "sess_xxxxx",
  "url": "{{BASE}}/app?s=sess_xxxxx",   // ← 把用户整页跳到这里
  "max_images": 20,                     // 出图额度(张);旧版「不限」会话此处为 -1
  "max_videos": 0,                      // 联动视频额度(条);不传 = 0 = 不能出片
  "max_scenes": 4,                      // 「加场景」一次最多补几个(账户档,只是操作节流)
  "expires_in": 86400                   // 链接有效期(秒)= ttl_hours × 3600
}

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

用户在页面上做什么

1. 上传户型图,用框选工具裁出一个房间。
2. 选空间/风格,再选一个灯光场景 → 生成。出 1 张图,扣 1 张额度。
3. 觉得像,就在图下面点「＋ 加灯光场景」补更多场景 —— 同一个房间、同一套家具,只换灯光。每补一张同样扣一张。
4. 有 2 个以上场景后,可以把它们串成一条联动视频(如果你给了视频额度)。
5. 下载。所有图和片都留在「我的作品」里,刷新、换设备都还在。

联动视频(可选)

用户对出好的效果图满意后,可以把这一套场景图串成一条智能灯光/窗帘联动演示片(片长跟着场景数走:3 个场景约 22 秒、4 个场景约 28 秒)——同一个房间、同一套家具,灯光按场景切换。这是给业主看的签单物料,不是另一张图。

• 前提:至少要两个已出的场景。用户出完第一张后,用「＋ 加灯光场景」补第二个,出片入口就会出现。所以给了 max_videos 的会话,图的额度至少给 2 张才用得上。
• 额度按「条」单独计,不占张数额度,两者互不影响。
• 计费是独立 SKU:视频有自己的单价(与每张图的价无关),同样成片交付成功才实扣,失败不收钱。一条片的段数 = 场景数(首镜直接落在第 1 个场景上),场景越多段数越多、价越高 —— 算法见计价方式,你的逐段单价带 Key 查 /api/v2/account。
• 用户不会看到金额。页面上他只看到「视频 1/1 条」这样的额度,看不到你的采购价 —— 这对所有会话都成立(包括你自己团队用的链接),不需要你在签发时做任何设置。
• 出片要几分钟(取决于场景数),页面上有进度与预计时间;成片挂在那件作品下,刷新、换设备都还在。

计价方式

两个 SKU 分开算:效果图按张、联动视频按条(逐段)。 单价都按账户约定 —— 这一页(公开)只讲算法,不挂数字; 你的价格带 Key 查 GET /api/v2/account(别人看不到),或直接问对接人。

效果图(按张)

每张一个价,按账户谈定(/api/v2/account 的 price_per_image_cents),与用户在页面上选了哪个出图模型无关 —— 换成更贵的那档也不加价,成本差由我们承担。

页面上开放给用户选的出图模型:读取中…。 默认那档是我们实测下来最贴户型、性价比最好的;其余保留给「这一张想换个感觉」的场合。

联动视频(按条,逐段计价)

片子从一段首镜(户型图俯冲进屋)开始,它直接落在第 1 个场景上; 之后每换一个场景各一段。所以 段数 = 场景数, 每多一个场景就多一段、多一段的钱。 你的逐段单价在 /api/v2/account 的 video_hero_cents(首镜)与 video_segment_cents(其余每段): 整条价 = 首镜 + (场景数 − 1) × 每段,自己就能算任意场景数。 例外只有一处:用户勾了「观影」且这单卖了影音设备时,片中会多插一段电视墙运镜 —— 那一条多一段的钱。

首镜比其余段贵,是因为它换了更强的一档 —— 「一张户型图纸变成实景并推进屋里」 是全片最难的一镜,便宜档在这里会幻觉出不存在的走廊、或者把图纸上的符号直接烧进画面。 其余段是在你已经出好的效果图之间做灯光过渡。

段数在用户点「确认」之前就定了,所以这条片扣多少下单当时就算得准; 金额只在你这边可见(/api/v2/usage 与自助面板), 页面上不会向用户显示任何金额。视频只有这一种收法(逐段计价)—— 没有一口价:成本随场景数线性涨,任何一口价都会在某个段数倒挂,那种账没法长期做。

计费

三句话

• 账户是预付余额。每交付一张图,扣一次单价;视频按条、单价另计。
• 只为「拿得到的东西」付费。技术性失败(模型没返回 / 图床拿不到地址)不计费、自动退回余额。只要图/片成功产出就计费,与用户「觉得像不像、满意不满意」无关。
• 余额不足时用户无法继续出图,充值后立即恢复。

为什么出图时余额会先降一截

出图前系统先冻结本次预估金额:balance_cents 立即下降、held_cents 等额上升;每交付一张转为实扣,没用掉的部分终态自动退回。所以轮询 /api/v2/account 看到余额降、held 升是正常的,不是提前扣费;部分失败后余额回升也正常。

成本与安全

你手上的四道闸

两个别误解的地方

• end_user_id 只是对账标签,不做任何限额、也不绑定/鉴权用户。要按用户控量,只能靠「每个用户单独签发 + 按需设 max_images」。
• 张数额度是尽力上限,不是精确硬闸:它只在提交新任务时拦截,已经在产的任务会把这一单出完(实际交付可比设定值多几张)。每日花费上限同理。请按此预留余量。

账户级默认限 8 单在途、60 次/分:超出分别返回 429 concurrency_limit / rate_limited,退避后重试即可;压量场景需要更高额度请联系对接人调整。

账户 / 用量(对账)

金额字段单位均为「分」(1 元 = 100 分) —— 对账时除以 100。

{ "balance_cents": 131110,          // 余额
  "held_cents": 0,                  // 出图中冻结(交付后转实扣,没用掉的退回)
  "price_per_image_cents": 200,     // 每张图单价(与所用模型无关)
  "provider": "seedream",           // 你账户默认的出图模型
  "video_price_from_cents": 2340,   // 最便宜那条片(2 个场景 = 3 段)多少钱
  "video_hero_cents": 1040,         // 你的首镜价(固定 1 段;按账户,示例数字)
  "video_segment_cents": 650,       // 每个场景 1 段
  "video_per_extra_scene_cents": 650, // 每多勾一个场景多收多少
  "video_markup_pct": 30,           // 逐段计价的加成率(视频只有这一种收法)
  "spent_today_cents": 19090,       // 今日已花(北京日)
  "spent_today_video_cents": 10890, // 其中视频花了多少
  "daily_spend_cap_cents": 0,       // 每日花费上限;0 = 未设
  "max_scenes_per_render": 4,       // 「加场景」一次最多补几张
  "status": "active", "sandbox": false, "timezone": "Asia/Shanghai" }

按北京时区拉取已交付明细(一张图一行,视频的 scene 为 video),用于你侧对账。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、公网可达)。状态共五种:base_ready / done / failed / cancelled / expired。

X-LightPlan-Signature: <hex>   X-LightPlan-Timestamp: 1781990000   X-LightPlan-Event: evt_xxx
{ "render_id":"..","account_id":"acct_..","status":"done",
  "images":[{"scene":"明亮","url":"https://.."}], "error":"", "created_ts":1781990000 }

验签:HMAC-SHA256(secret, "{timestamp}.{原始请求体}"),并拒绝早于 5 分钟的重放(每次投递——含重试——都按发送时刻现签,放心按 5 分钟卡)。X-LightPlan-Event 是事件唯一 ID —— 重试会重复投同一事件,按这个头去重。

投递语义:我们不跟随重定向,3xx / 4xx 响应(408、429 除外)视为你侧配置错误、该事件立即作废不再重试 —— 请登记最终 URL 并直接返回 2xx;5xx / 超时会退避重试,最多 8 次、约 42 分钟内打完。回调是尽力投递,以 /api/v2/usage 为对账真相源。回调体内嵌的图片 URL 是长期有效的直链,请按敏感数据处理。

错误码

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

FAQ

会员/非会员怎么区分?

我们不区分,也不介入你的会员体系 —— 你卖给用户什么档位是你的事,对我们只体现为一个数:这条会话给几张(max_images)、给不给视频(max_videos)。想给 VIP 更多,就把数写大。

一个会话能出多少图?

max_images 张,写多少就是多少;每交付一张扣一张。0 或不传 = 不能出图 —— 没有「不限」。

怎么先联调不花钱?

到 自助接入大厅一键领沙箱 Key(免费、秒发):返回占位图、¥0 完全免费不计费,流程与生产一致,联调通过后换生产 Key。

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

单个空间的局部图(裁好的一个房间),白底清晰、短边 ≥ 600px;文件 ≤ 12MB、分辨率 ≤ 8000 万像素。我们页面带框选工具帮用户从整套图里裁出一个房间。
常见坑:CAD 直接导出的超高分辨率线稿(文件不大但上亿像素)会被按「分辨率过高」拒收 —— 导出普通分辨率即可,不是图不够清晰,别反向去导更大的图。

出的图带标识吗?

按国标要求,所有 AI 生成图都写入隐式元数据标识;自助开户转正式的账户,出图默认还带右下角「AI生成」可见角标。签约合作的商户可约定关闭可见角标(显式标识责任随合同划转)—— 需要请联系对接人。

自助开户(/portal)遇到的错误码怎么查?

signup_* 系列不在上表(上表只覆盖 Bearer 接口),开户页面上有对应的人话提示。