接入文档

快速开始

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

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

鉴权

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

Authorization: Bearer lp_live_xxxxxxxxxxxxxxxxxxxx

创建会话

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

请求体

让同一个用户下次进来还是他自己的那一份(resume)

额度和「我的作品」都跟着会话走,不跟着 end_user_id 走。所以签发方式决定了用户看到什么:

带 resume 时:

• 这个 end_user_id 签发过(哪怕已过期)→ 返回他最近那条会话的同一个 session_token,有效期从现在起重算 ttl_hours,响应里 resumed: true;没签发过 → 照常新建,resumed: false。
• max_images / max_videos 此时是这个用户的总额度(绝对值,不是增量):每次都传 60 = 他一共 60 张,用掉的不会回来;不传 = 不动。想给他再加 60 张,传 images_used + 60(images_used 在响应里)。传得比已用还小 = 关停他后续出图,已交付的不受影响。也可以传 images_remaining / videos_remaining:传 N = 让他剩余正好 N 张/条,我们按已用 + 正在出的自动算总额度,适合商户自己管剩余数的集成;与 max_* 同传返回 400 quota_fields_conflict。
• 要给某个用户换一条链接(比如链接外泄):这一次不带 resume 签发即可 —— 新的这条从此就是他「最近那条」,之后带 resume 都落在它上面。旧链接里的作品不会自动跟过来,需要的话联系对接人合并。

示例

总共 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"
  }'

你的用户 u_8841 每次从你的入口进来(一共给他 60 张、4 条片):{ "max_images": 60, "max_videos": 4, "end_user_id": "u_8841", "resume": true } —— 每次都原样传这一句即可。

单张体验:{ "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
  "resumed": false,                     // true = 续用了这个用户以前的会话(token 与上次相同)
  "images_used": 0,                     // 这条会话已交付的张数(续用时接着算)
  "images_remaining": 20,               // 还能出几张(已减去正在出的);旧版「不限」会话为 null
  "videos_used": 0,
  "videos_remaining": 0
}

拿到 url 后跳转即可(window.location = url)。会话 token 随机不可猜,但「不可猜」不等于「可公开分发」 —— 谁拿到这个 url,谁就能在有效期内用它出图(算你账)。务必按用户单独签发(别把一条链接发给多个人、别公开张贴),详见成本与安全。

用户在页面上做什么

1. 上传户型图,用框选工具裁出一个房间。已有效果图的可以直接传效果图(上传卡上二选一):不再从户型图重建房间,上传的图本身就是底图 —— 房间就是图里那间,风格、吊顶、地面不用再选,出的每张场景图与原图同构图同尺寸。原图不计张数;裁剪层用来框掉 logo、水印和图框(留在图里会被复制进每一张场景图),画面里不要有人。
2. 选空间/风格,再选一个灯光场景 → 生成。出 1 张图,扣 1 张额度。色温可选(2700K / 3000K / 3500K / 4000K):不选就跟随各场景的默认色温;选了,这件作品之后加的场景、修改、重出也都按它出,只改光的颜色、不改开哪些灯(浪漫场景的彩色氛围光照旧保留)。
3. 觉得像,就在图下面点「＋ 加灯光场景」补更多场景 —— 同一个房间、同一套家具,只换灯光。每补一张同样扣一张。出过的场景也能再选一次再出一张(结果不同):同一场景的几张放在同一个框里左右切换,图名叫 明亮1、明亮2、观影1……用户在框里挑更满意的那张;每出一张同样扣一张。
4. 觉得房间不像(家具位置、朝向、门窗对不上),点底图框上的「再抽一张」(重出底图):按同一张户型图重新出一版基础图,可以写一句「上一版哪里不像」让模型优先修正;新版和当前版一起放在底图框里左右对比,不会自动替换当前底图。重出一次同样扣 1 张。(它和「加场景」是两件事:加场景只换灯光、房间不变;重出底图换的是房间。)
5. 图里哪一处不对,点那张图上的「修改」:在图上圈出位置、每处写一句怎么改,模型在这张图的基础上只改那几处、其它保持不变,改好的作为同一场景的新一张追加(改灯光 —— 色温、明暗、哪几盏灯亮 —— 要选「整体调整」,光会照到圈外;写的内容像整体改法时页面会提醒);改一次同样扣 1 张。改的是第一张(基础图)时,之后再加的场景都按改好的图出 —— 想让视频里的房间更准,先把基础图改准。
6. 底图可以自己选:底图的各个版本(第一张、重出的、修改过的)都在底图框里,当前那版挂着「当前底图」标,它就是「加场景」的出发点。改过基础图之后,改好的那张自动成为底图;重出的那版不自动换 —— 对比后点它的「设为底图」才换。要是换完还是觉得上一版更像,再切回去 —— 换底图不出图、不扣额度,来回切都不花钱。
7. 有 2 个以上场景后,可以把它们串成一条联动视频(如果你给了视频额度)。
8. 下载。所有图和片都留在这条链接的「我的作品」里,刷新、换设备(同一条链接)都还在。作品跟着链接走:想让同一个用户下次从你的入口进来还能看到之前的作品,签发时带 resume。

联动视频(可选)

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

• 前提:至少要两个不同的已出场景。用户出完第一张后,用「＋ 加灯光场景」补第二个,出片入口就会出现(同一场景出的几张只算一个场景;镜头就是图:用户在出片第一步按图名排镜头 —— 明亮2 切 就餐3 切 浪漫1 —— 同一场景只能选一张,不选就用当前底图那一支里最新的一张)。所以给了 max_videos 的会话,图的额度至少给 2 张才用得上。
• 额度按「条」单独计,不占张数额度,两者互不影响。
• 计费是独立 SKU:视频有自己的单价(与每张图的价无关),同样成片交付成功才实扣,失败不收钱。一条片的段数 = 场景数(首镜直接落在第 1 个场景上),场景越多段数越多、价越高 —— 算法见计价方式,你的逐段单价带 Key 查 /api/v2/account。
• 用户不会看到金额。页面上他只看到「视频 1 条」这样的剩余额度,看不到你的采购价 —— 这对所有会话都成立(包括你自己团队用的链接),不需要你在签发时做任何设置。
• 出片要几分钟(取决于场景数),页面上有进度与预计时间;成片挂在那件作品下,刷新、换设备都还在。
• 片尾是用户自己的品牌位:出片前可上传 logo、填品牌名与一句引导语(默认品牌名 = 你的账户名,三样都可留空),浏览器会记住上次填的;片尾那句默认空白,由用户自己写品牌或引导语,不填就不说不写;填了只念出来、不上字幕 —— 品牌名和引导语已经用大字写在尾板上,同一句话不在画面上写第二遍。片子里没有我们的任何字样。

计价方式

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

效果图(按张)

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

页面上开放给用户选的出图模型:读取中…。用户选了哪个模型出图,之后「修改」这张图也用它(改不了),所以页面在选模型时就会提示各模型的修改精度。 每个模型还带一句说明(接口里的 hint:它是什么、什么时候选它),页面选模型时同样显示。 默认那档是我们实测下来最贴户型、性价比最好的;其余保留给「这一张想换个感觉」的场合。

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

片子从一段首镜(户型图俯冲进屋)开始,它直接落在第 1 个场景上; 之后每换一个场景各一段。所以 段数 = 场景数, 每多一个场景就多一段、多一段的钱。 从效果图出发的作品没有户型图,也就没有首镜:片子直接从第 1 个场景的定格开始,段数 = 场景数 − 1,少的正是最贵的那一段,片长短 5 秒多。 你的逐段单价在 /api/v2/account 的 video_hero_cents(首镜)与 video_segment_cents(其余每段): 整条价 = 首镜 + (场景数 − 1) × 每段,自己就能算任意场景数。 例外只有一处:用户勾了「观影」且这单卖了影音设备时,片中会多插一段电视墙运镜(从全景推到正对挂墙电视的特写、停一拍再回来;推过去的落点由出图模型先出一张电视特写「落幅图」钉住)—— 那一条多一段的钱,外加这一张落幅图的钱(/api/v2/account 的 video_closeup_cents)。

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

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

计费

三句话

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

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

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

成本与安全

你手上的四道闸

两个别误解的地方

• end_user_id 只是对账标签,不做任何限额、也不绑定/鉴权用户。要按用户控量有两种做法:① 签发时带 resume —— 同一个 end_user_id 拿回同一条会话,max_images 就是他的总额度,用掉的不会因为重新签发而回来;② 不带 resume、每次新签发,那么每一条都是全新的额度(每次传 60 = 每次进来都有 60 张),要控量得你自己记账、按剩余量传 max_images。
• 张数额度是硬闸,每日花费上限不是 —— 两者别混为一谈。max_images / max_videos:用户每次提交时,就按「这次要出几张」把额度先占住(已用 + 正在出的 + 这一次 ≤ 额度,否则当场拒绝),多开几个页面同时点也刷不穿,实际交付不会超过你设的数;没出成的那几张自动还回额度。每日花费上限则只按已交付的金额判断、不含正在出的,命中前已经在出的任务会照常出完,当天实际花费可能比上限多出这几单 —— 请按此给它留余量。(早期「不限」会话 max_images = -1 没有张数闸,只受余额与每日上限约束。)

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

账户 / 用量(对账)

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

{ "balance_cents": 131110,          // 余额
  "held_cents": 0,                  // 出图中冻结(交付后转实扣,没用掉的退回)
  "price_per_image_cents": 200,     // 每张图单价(与所用模型无关)
  "provider": "gptimage",           // 你账户默认的出图模型(2026-09-10 起默认 GPT Image 2.5 正式版;gptimage_flash = 2.5 Flash 档)
  "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),用于你侧对账。每行的 end_user_id 就是你签发这条会话时传的那个,图和视频都带 —— 按人汇总消耗只看这一列;加 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、公网可达)。状态共五种: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 接口),开户页面上有对应的人话提示。