图像背景生成 — 创建任务

POST

/services/aigc/background-generation/generation/

cURL

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx-background-generation-v2",
  "input": {
    "base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
    "ref_image_url": "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg",
    "ref_prompt": "山脉和晚霞",
    "reference_edge": {
      "foreground_edge": [
        "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png",
        "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/2c36cc4b7da027279e87311dac48fc2d5d784b1e72c0e-x4f1wC_fw658webp.png"
      ],
      "background_edge": [
        "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/0718a9741e07c52ca5506e75c4f2b99e22fff68a4c7d3-P9WGLr_fw658webp.png"
      ],
      "foreground_edge_prompt": [
        "粉色桃花",
        "可爱小狗"
      ],
      "background_edge_prompt": [
        "树叶"
      ]
    }
  },
  "parameters": {
    "n": 4,
    "ref_prompt_weight": 0.5,
    "model_version": "v3"
  }
}'

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

请先获取 API Key 并设置为环境变量。

模型概览

模型简介

模型名	模型简介
wanx-background-generation-v2	Wan-图像背景生成模型，为主体商品生成背景图，适用于电商和海报场景。支持多种背景生成方法：文本引导、图像引导、文本与图像结合引导，以及文本、图像与边缘引导元素的综合应用。

计费与限流

模型名	计费单价	任务下发接口 QPS 限制	同时处理中任务数量	免费额度
wanx-background-generation-v2	0.08元/张	2	1	500张

边缘引导元素生成方法

边缘引导元素生成方法因其能够有效保留图像中的边缘和结构信息，在图像背景生成任务中常用于生成前景或背景元素图像。 步骤1：PS 抠图，导出带透明背景的 4 通道格式图像。 步骤2：生成边缘引导元素图像。针对步骤2，提供两种方案，任选一种即可。 方案一：ModelScope 在线生成 访问 ModelScope 背景图 edge 元素生成，直接上传第一步抠图后的图像点击运行即可获得符合要求的元素图像。 方案二：使用代码本地生成 安装依赖包：

pip install controlnet-aux==0.0.7

运行以下 Python 脚本生成边缘引导元素：

import numpy as np
from PIL import Image
from controlnet_aux.processor import Processor

hed_processor = Processor('softedge_hed')


def make_elements(name):
  img=Image.open(name)
  img=np.array(img)
  img[:,:,:-1]=img[:,:,:-1]*(img[:,:,-1:]>127)
  img=Image.fromarray(img,mode='RGBA')
  r,g,b,a=img.split()
  img=Image.merge(mode='RGB',bands=[r,g,b])
  edge = hed_processor(img, to_pil=True).resize(img.size).convert('RGB')
  edge.putalpha(a)
  edge=np.array(edge)
  edge[:,:,:-1]=edge[:,:,:-1]*(edge[:,:,-1:]>50)
  edge=Image.fromarray(edge,mode='RGBA')
  edge.save('result.png')


# 使用方法：将步骤1导出的前景图路径传入
make_elements('foreground.png')

错误码

大模型服务通用状态码请查阅错误信息。本模型还有如下特定错误码：

HTTP 返回码	错误码（code）	错误信息（message）	含义说明
400	InvalidParameter.DataInspection	Download the media resource timed out during the data inspection process.	可能原因：图片所属服务器不稳定，导致下载超时

常见问题

wanx-background-generation-v3 模型不存在

报错场景：如果将 model 参数设置为 wanx-background-generation-v3，发送请求后报错显示模型不存在。

{
    "code": "InvalidParameter",
    "message": "Model not exist.",
    "request_id": "539f3cf9-9b9c-9a0f-988f-1829c7eb502f"
}

原因及解决方案：目前图像背景生成只有 wanx-background-generation-v2 这一个模型。如果需要切换 V3 模型，请设置 parameters.model_version 为 v3，才能成功调用 v3 模型。

使用示例图片报错提示需要提供 RGBA 模式的图片

报错场景：将文档的示例图片下载到本地后重新上传，使用新链接请求时报错图像格式是 RGB 而非 RGBA。

{
    "request_id": "8f7d6829-281a-9270-944b-xxxxxx",
    "output": {
        "task_id": "72a2d266-6822-4165-a6e4-xxxxxx",
        "task_status": "FAILED",
        "submit_time": "2024-11-07 09:51:19.xxx",
        "scheduled_time": "2024-11-07 09:51:19.xxx",
        "end_time": "2024-11-07 09:51:20.xxx",
        "code": "BadRequest.UnsupportedFileFormat",
        "message": "Base image require RGBA format, but is RGB, modes concept see https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-modes"
    },
    "usage": {
        "image_count": 0
    }
}

主要原因：主体图像、前景元素图像或背景元素图像不是 RGBA 图像。图片从示例链接下载后再上传的过程中可能改变原始格式，例如：下载时使用不支持透明度的格式（如 .jpg、.jpeg）、上传至存储服务器时不支持 RGBA 格式，或图像编辑工具未保留透明度。 解决方案：确保图像保存为支持 RGBA 透明通道的格式（如 .png），并在整个上传流程中保留透明度信息。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

Header 参数

enum<string>

必填

请求内容类型，必须设置为 application/json。

可选值：application/json

string

必填

千问云 API Key。详见获取 API Key。

enum<string>

必填

异步处理配置参数。HTTP 请求只支持异步，必须设置为 enable。缺少此请求头将报错："current user api does not support synchronous calls"。

可选值：enable

string

千问云业务空间 ID。示例值：llm-xxxx。主账号 API-Key 可不填；RAM 子账号 API-Key 必填。

请求体

application/json

enum<string>

必填

模型名称。当前仅支持填写 wanx-background-generation-v2。通过 parameters.model_version 参数切换 v2/v3 版本，请勿将 model 设置为 wanx-background-generation-v3。

可选值：wanx-background-generation-v2

示例:wanx-background-generation-v2

object

必填

输入图像的基本信息。ref_image_url 和 ref_prompt 至少需要填写一个。

显示子属性

string

必填

主体图像 URL。主体图像必须为带透明背景的 RGBA 四通道 PNG 图像，输出图像的分辨率与该图像保持一致。图像长边不超过 2048 像素。

示例:https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png

string

引导图像 URL。用于引导背景风格。与 ref_prompt 至少需要填写一个。支持 jpg、png、webp 等常见格式。引导图像可以是 RGB 图像或带透明背景的 RGBA 图像。

示例:http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg

string

引导文本提示词，支持中英双语。与 ref_image_url 至少需要填写一个。英文最多支持 150 个单词，中文约 100-120 个中文字符，超过部分会被自动忽略。示例：山脉和晚霞。

示例:山脉和晚霞

string

负向提示词，描述画面不希望出现的内容。一般不填，使用模型内置的默认值。英文最多支持 150 个单词，中文约 100-120 个中文字字符。示例：低质量的，模糊的，错误的。

object

边缘引导元素图像，包括前景元素图像列表和背景元素图像列表。

显示子属性

string[]

前景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像，分辨率和主体图像相同。所有前景元素生成的图层在主体前面，可以对主体形成遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。

string[]

前景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 foreground_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。

string[]

背景元素图像 URL 列表。每个图像必须为带透明背景的 RGBA 四通道图像。生成图层在主体的后面，如果重叠会被主体遮挡。foreground_edge 和 background_edge 图像列表之和不得超过 10。

string[]

背景元素列表对应的 prompt 列表。如果输入该参数，长度必须和 background_edge 列表相等，且顺序一一对应。无需填写某个元素的 prompt 时，可用空字符串占位。

string

已废弃

已废弃，建议使用图配文。图像上添加文字主标题，算法自动确定文字的大小和位置，限制 1-8 个字符。

取值范围：length: 1–8

string

已废弃

已废弃，建议使用图配文。图像上添加文字副标题，算法自动确定文字的大小和位置，限制 1-10 个字符。仅当 title 不为空时生效。

取值范围：length: 1–10

object

图像处理参数。

显示子属性

integer

默认值1

图片生成的数量，支持 1-4 张，默认值 1。

示例:4

取值范围：1 <= x <= 4

enum<string>

默认值"v2"

模型版本。v2：旧版模型，速度快（默认值）。v3：新版模型，速度稍慢但效果更好，推荐切换到 v3。

可选值：v2,v3

示例:v3

integer

默认值300

当 ref_image_url 不为空时生效。该参数在图像引导的过程中添加随机变化，数值越大生成背景与引导图像的相关性越低。默认值 300，取值范围 [0, 999]。

取值范围：0 <= x <= 999

number

默认值0.5

仅当 ref_image_url 和 ref_prompt 同时输入时生效，表示引导文本 prompt 的权重。取值范围 [0, 1]，默认值 0.5。数值越大表示引导文本对生成背景的影响程度越大。

示例:0.5

取值范围：0 <= x <= 1

enum<string>

已废弃

已废弃，不建议使用。使用场景：GENERAL（通用场景，默认值）、ROOM（室内家居场景）、COSMETIC（美妆场景，也适用于大部分小商品摆放场景）。

可选值：GENERAL,ROOM,COSMETIC

响应

200-application/json

string

请求唯一标识。可用于请求明细溯源和问题排查。

示例:4909100c-7b5a-9f92-bfe5-xxxxxx

object

任务输出信息。

显示子属性

string

任务 ID。用于查询任务状态及结果，查询有效期 24 小时。

示例:0385dc79-5ff8-4d82-bcb6-xxxxxx

enum<string>

任务状态。

可选值：PENDING,RUNNING,SUCCEEDED,FAILED,CANCELED,UNKNOWN

​模型概览

​边缘引导元素生成方法

​错误码

​常见问题

​wanx-background-generation-v3 模型不存在

​使用示例图片报错提示需要提供 RGBA 模式的图片

鉴权

Header 参数

请求体

响应

模型概览

边缘引导元素生成方法

错误码

常见问题

wanx-background-generation-v3 模型不存在

使用示例图片报错提示需要提供 RGBA 模式的图片