通义千问-图像编辑API参考

通义千问-图像编辑模型(Qwen-Image-Edit)支持精准的中英双语文字编辑、调色、细节增强、风格迁移、增删物体、改变位置和动作等操作,可实现复杂的图文编辑。

快速入口:在线体验 使用指南 技术博客

效果展示

多图图像修改展示器
原图
修改后的图

模型概览

模型名称

计费单价

限流(主账号与RAM子账号共用)

免费额度(查看)

任务下发接口RPS限制

同时处理中任务数量

qwen-image-edit

0.3元/张

2

2

100

前提条件

在调用前,您需要开通模型服务并获取API Key,再配置API Key到环境变量

如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持PythonJava。

HTTP调用

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

请求参数

图像编辑

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-edit",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"
                    },
                    {
                        "text": "将图中的人物改为站立姿势,弯腰握住狗的前爪"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "negative_prompt": "",
        "watermark": false
    }
}'
请求头(Headers)

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

请求体(Request Body)

model string (必选)

模型名称。示例值:qwen-image-edit。

input object (必选)

输入的基本信息,如提示词等。

属性

messages array (必选)

模型对话列表。目前只支持单轮对话,即传入一组role、content参数,不支持多轮对话

属性

role string (必选)

消息的角色。此参数必须设置为user

content list (必选)

消息的内容,包括图像与提示词。注意:content只能包含一个 image 和 一个text。

属性

image string (必选)

输入图像的URL或 Base64 编码数据。只支持传入一张图片。

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽度和高度范围为[384, 3072]像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

输入图像说明:

  1. 使用公网可访问URL

    • 支持 HTTP 或 HTTPS 协议。本地文件请参见上传文件获取临时URL

    • 示例值:https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg

  2. 传入 Base64 编码图像后的字符串

    • 数据格式:data:{MIME_type};base64,{base64_data}

    • 示例值:data:image/jpeg;base64,GDU7MtCZzEbTbmRZ......

    • 示例中的编码字符串不完整,仅做演示,更多内容请参见传值方式

text string (必选)

正向提示词,用来描述生成图像中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

示例值:一只坐着的橘黄色的猫,表情愉悦,活泼可爱,逼真准确。

parameters object (可选)

图像处理参数。

属性

negative_prompt string (可选)

反向提示词,用来描述不希望在画面中看到的内容,可以对画面进行限制。

支持中英文,长度不超过500个字符,超过部分会自动截断。

示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。

watermark boolean (可选)

是否添加水印标识,水印位于图片右下角,文案为“Qwen-Image”。

  • false:默认值,不添加水印。

  • true:添加水印。

seed integer (可选)

随机数种子。取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。

如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

提示:模型生成过程具有概率性,因此即使使用相同的 seed,也不能保证每次生成结果完全一致。

响应参数

任务执行成功

任务数据(如任务状态、图像URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "width": 1248,
        "image_count": 1,
        "height": 832
    },
    "request_id": "bf37ca26-0abe-98e4-8065-xxxxxx"
}

任务执行异常

如果因为某种原因导致任务执行失败,将返回相关信息,可以通过codemessage字段明确指示错误原因。请参见错误信息进行解决。

{
    "request_id": "31f808fd-8eef-9004-xxxxx",
    "code": "InvalidParameter",
    "message": "content length only support 2"
}

output object

任务输出信息。

属性

choices array

模型生成的内容,类型为的数组,可以包含一个或多个choices对象。

属性

finish_reason string

自然停止时输出为stop。

messages object

输出的消息。

属性

role string

消息的角色,固定为assistant

content array

属性

image string

模型生成图片的URL地址。有效期24小时,请及时下载并保存图像。

与原图的长宽比保持一致。

usage object

输出信息统计。只对成功的结果计数。

属性

image_count integer

模型生成图片的数量。

当前固定为1。

width integer

模型生成图片的宽度,单位像素。

height integer

模型生成图片的高度,单位像素。

request_id string

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

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

DashScope SDK调用

DashScope SDK目前已支持PythonJava。

SDKHTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用

Python SDK调用

说明
  • 请先确认已安装最新版DashScope Python SDK,否则可能运行报错:安装SDK

  • 不支持异步接口。

请求示例

传入图片公网URL

import json
import os
from dashscope import MultiModalConversation

messages = [
    {
        "role": "user",
        "content": [
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"},
            {"text": "将图中的人物改为站立姿势,弯腰握住狗的前爪"}
        ]
    }
]

# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-edit",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=True,
    negative_prompt=""
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
else:
    print(f"HTTP返回码:{response.status_code}")
    print(f"错误码:{response.code}")
    print(f"错误信息:{response.message}")
    print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")

传入图片Base64编码

Base64编码格式说明请参见传值方式

import json
import os
from dashscope import MultiModalConversation
import base64
import mimetypes


# ---用于 Base64 编码 ---
# 格式为 data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("不支持或无法识别的图像格式")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"


# 获取图片的 Base64 编码
# 下面的地址需要修改为实际的文件路径,否则无法运行
image = encode_file("./dog_and_girl.jpeg")

messages = [
    {
        "role": "user",
        "content": [
            {"image": image},
            {"text": "将图中的人物改为站立姿势,弯腰握住狗的前爪"}
        ]
    }
]

# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-edit",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=True,
    negative_prompt=""
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
    print(response.output.choices[0].message.content)
else:
    print(f"HTTP返回码:{response.status_code}")
    print(f"错误码:{response.code}")
    print(f"错误信息:{response.message}")
    print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")

响应示例
图像链接的有效期为24小时,请及时下载图像。
{
    "status_code": 200,
    "request_id": "3daccb10-10ca-9399-8b6a-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "width": 1248,
        "image_count": 1,
        "height": 832
    }
}

Java SDK调用

说明

请先确认已安装最新版DashScope Java SDK,否则可能运行报错:安装SDK

请求示例

图像编辑

import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class QwenImageEdit {

    // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {

        MultiModalConversation conv = new MultiModalConversation();

        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"),
                        Collections.singletonMap("text", "将图中的人物改为站立姿势,弯腰握住狗的前爪")
                )).build();

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("watermark", true);
        parameters.put("negative_prompt", "");

        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .apiKey(apiKey)
                .model("qwen-image-edit")
                .messages(Collections.singletonList(userMessage))
                .parameters(parameters)
                .build();

        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

图像编辑(使用Base64编码)

Base64编码格式说明请参见传值方式

import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.*;

public class QwenImageEdit {

    // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {

        //下面的地址需要修改为实际的文件路径,否则无法运行
        String image = encodeFile("src/main/java/org/xxx/dog_and_girl.jpeg");

        MultiModalConversation conv = new MultiModalConversation();

        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("image", image),
                        Collections.singletonMap("text", "将图中的人物改为站立姿势,弯腰握住狗的前爪")
                )).build();

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("watermark", true);
        parameters.put("negative_prompt", "");

        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .apiKey(apiKey)
                .model("qwen-image-edit")
                .messages(Collections.singletonList(userMessage))
                .parameters(parameters)
                .build();

        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    /**
     * 将文件编码为Base64字符串
     * @param filePath 文件路径
     * @return Base64字符串,格式为 data:{MIME_type};base64,{base64_data}
     */
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("文件不存在: " + filePath);
        }
        // 检测MIME类型
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("无法检测文件类型: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("不支持或无法识别的图像格式");
        }
        // 读取文件内容并编码
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("无法读取文件内容: " + filePath);
        }

        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }

    public static void main(String[] args) {
        try {
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
响应示例
image的链接有效期为24小时,请及时下载图像。
{
    "requestId": "9e59e2da-28b0-9468-b356-5d2beea8a477",
    "usage": {},
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
                        }
                    ]
                }
            }
        ]
    }
}

输入图像说明

传值方式

方式一:使用公网URL

  • 提供一个公网可访问的图像地址,支持 HTTP 或 HTTPS 协议。本地文件请参见上传文件获取临时URL

  • 示例值:https://xxxx/img.png

方式二:使用Base64编码

将本地图片文件转换为 Base64 格式的字符串,并按格式拼接:data:{MIME_type};base64,{base64_data}

  • {MIME_type}:图像的媒体类型,需与文件格式对应。

  • {base64_data}:图像文件经过 Base64 编码后的字符串。

  • 图像格式与MIME 类型对应关系:

    图像格式

    MIME Type

    JPEG

    image/jpeg

    JPG

    image/jpeg

    PNG

    image/png

    BMP

    image/bmp

    TIFF

    image/tiff

    WEBP

    image/webp

  • 示例值"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDg......"

    注意:为便于展示,上述 Base64 字符串是截断的。在实际使用中,请务必传入完整的编码字符串。

  • 示例代码请参见Python SDK调用Java SDK调用

图像访问配置

配置域名白名单:确保业务系统可访问图像链接

模型生成的图像存储于阿里云OSS,每张图像会被分配一个OSS链接,如https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png。OSS链接允许公开访问,您可以使用此链接查看或者下载图片,链接仅在 24 小时内有效。

特别注意的是,如果您的业务对安全性要求较高,无法访问阿里云OSS链接,您需要单独配置外网访问白名单。请将以下域名添加到您的白名单中,以便顺利访问图片链接。

# OSS域名列表
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

错误码

如果模型调用失败并返回报错信息,请参见错误信息进行解决。