云凡智联

首页/开放能力

imageBackground

一键换背景

上传主体图，自动保留主体并替换背景；可填写背景描述或上传背景参考图，默认使用浅灰摄影棚背景。

2-6积分/次

基础说明

上传主体图，自动保留主体并替换背景；可填写背景描述或上传背景参考图，默认使用浅灰摄影棚背景。

提交任务

保留输入图片中的主体，仅替换背景。服务端自动拼接主体保留、光影融合与质量约束，创建一个图片任务。

POST/api/third-party/imageBackground/generate

请求头

字段	类型	必填	说明
X-API-Token	string	是	平台提供的调用凭证，用于识别当前账号或租户。
Content-Type	string	是	提交任务时固定使用 application/json。

请求参数

字段	类型	必填	说明
image	string	是	主体图片的公网 HTTP/HTTPS URL。
backgroundImage	string	否	背景参考图 URL；作为第二张参考图，仅参考其场景、配色和氛围，可省略或传空字符串。
prompt	string	否	目标背景描述，最多9000字符；不填且无背景参考图时使用默认浅灰摄影棚背景。有参考图时，描述用于补充背景要求。
model	string	否	模型，可传 Nano Banana 2、Nano Banana Pro、gpt-image-2、gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst 或 Seedream 5.0 Pro；默认 Nano Banana 2。
resolution	string	否	默认 2k；gpt-image-2.5 默认且仅支持 1k；其他限制与图片生成一致。
aspectRatio	string	否	输出比例，如 1:1、4:3、16:9、auto。Seedream 5.0 Pro 默认 1:1，仅支持 1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9、9:21；传 auto 时自动转换为 1:1。

请求示例

bash

curl -X POST "https://yunfanzhilian.com/api/third-party/imageBackground/generate" \
  -H "X-API-Token: your_token" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.com/product.jpg","prompt":"温暖自然的木质桌面，背景是柔和虚化的客厅","model":"Nano Banana 2","resolution":"2k","aspectRatio":"auto"}'

响应字段

字段	类型	必填	说明
code	number	-	业务状态码，200 表示请求成功。
message	string	-	本次请求的结果说明。
data.taskId	string	-	任务 ID。提交成功后请保存，用于查询生成结果。
data.cost	number	-	本次提交预扣积分。
data.status	string	-	任务初始状态，通常为 pending 或 processing。
timestamp	string	-	响应时间，ISO 8601 格式。
data.prompt	string	-	实际提交给模型的完整提示词，包含主体保留与背景要求。

响应示例

json

{
  "code": 200,
  "message": "一键换背景任务已提交",
  "data": {
    "taskId": "task_xxxxxxxx",
    "status": "pending",
    "model": "Nano Banana 2",
    "resolution": "2k",
    "aspectRatio": "auto",
    "cost": 4,
    "prompt": "以第一张图片为唯一主体参考，仅替换背景。完整保留主体的形状、比例、颜色、材质、纹理、文字、Logo和细节，不增删主体，不改变主体姿态与拍摄角度。\n保持原图中主体的位置、大小、占画面比例与摆放方式。原图接触地面或台面的主体必须继续稳稳放在台面上，底部与台面接触，不要悬浮、抬高或改变重心。\n目标背景要求：简洁高级的浅灰色摄影棚背景，柔和渐变，干净台面，适合电商商品展示。\n让新背景与主体的透视、光源方向、色温和景深协调，生成自然的接触阴影与必要的反射，保持主体真实质感。\n主体边缘干净自然，无白边、抠图痕迹、变形或多余物体。不要新增文字、水印、边框或Logo，输出清晰、自然的商业摄影图片。"
  }
}

注意事项

主体保留提示词：以第一张图片为唯一主体参考，仅替换背景。完整保留主体的形状、比例、颜色、材质、纹理、文字、Logo和细节，不增删主体，不改变主体姿态与拍摄角度。
主体摆放提示词：保持原图中主体的位置、大小、占画面比例与摆放方式。原图接触地面或台面的主体必须继续稳稳放在台面上，底部与台面接触，不要悬浮、抬高或改变重心。
默认背景提示词：简洁高级的浅灰色摄影棚背景，柔和渐变，干净台面，适合电商商品展示。
背景参考图提示词：第二张图片仅作为背景参考，参考其场景、配色、构图和氛围，不引入第二张图片中的人物、商品、文字或Logo。
光影融合提示词：让新背景与主体的透视、光源方向、色温和景深协调，生成自然的接触阴影与必要的反射，保持主体真实质感。
质量约束提示词：主体边缘干净自然，无白边、抠图痕迹、变形或多余物体。不要新增文字、水印、边框或Logo，输出清晰、自然的商业摄影图片。
提交响应 data.prompt 返回实际使用的完整提示词；消费记录按一键换背景单独统计。
参考图建议使用可公网访问的 HTTPS URL。
所有图片模型只尝试一次原模型；1K/2K 失败后统一由火山方舟 Seedream 5.0 Pro 按相同分辨率兜底一次，4K 失败直接退款。Seedream 自身失败不再重试；特价版失败直接退款，不使用兜底。
每次上游尝试最多等待 7 分钟取得结果 URL，不包含下载耗时；查询确认仍无结果时按上述规则兜底。临时查询网络异常保持处理中，已完成结果优先返回。兜底不额外扣积分，最终失败按原扣费退款。
Seedream 5.0 Pro：1K 3 积分、2K 6 积分。
gpt-image-2：1K/2K/4K 分别为 4/5/6 积分；gpt-image-2.5：仅支持 1K，为 2 积分；gpt-image-2.5-flare：1K/2K/4K 分别为 2/3/4 积分；gpt-image-2.5-sunburst：1K/2K/4K 分别为 2/3/4 积分；Nano Banana 2：1K/2K/4K 分别为 4/4/4 积分；Nano Banana Pro：1K/2K/4K 分别为 4/4/4 积分。
提交接口只负责创建任务，生成结果请通过获取结果接口查询。
服务端不设置提交并发上限，上游服务自身的限流仍可能返回 429。