El modelo de Generación y Edición de Imágenes Qwen admite tanto texto a imagen (T2I) como imagen a imagen/edición de imágenes (I2I). Puede generar imágenes directamente a partir de prompts de texto o editar imágenes basándose en imágenes de referencia combinadas con instrucciones de edición. Admite tanto los protocolos compatibles con OpenAI como DashScope.
Resumen de modelos
Modelo | Descripción | Especificaciones de la imagen de salida |
|---|---|---|
qwen-image-3.0-pro | Modelo Qwen de Generación y Edición de Imágenes 3.0 que admite tanto texto a imagen (T2I) como imagen a imagen/edición de imágenes (I2I). | Resolución de imagen:
Formato de imagen: PNG |
qwen-image-3.0 | Modelo estándar Qwen de Generación y Edición de Imágenes 3.0 que admite tanto texto a imagen (T2I) como imagen a imagen/edición de imágenes (I2I). Equilibra calidad y velocidad. | |
qwen-image-2.1-pro | Modelo Pro Qwen de Generación y Edición de Imágenes 2.1. La conversión de imagen a imagen/edición de imágenes (I2I) admite hasta 10 imágenes de referencia. También puede decidir automáticamente si generar una imagen estándar o una imagen con canal transparente (alfa) basándose en la descripción del prompt. | |
qwen-image-2.1-turbo | Modelo Turbo Qwen de Generación y Edición de Imágenes 2.1. El modelo más equilibrado y rentable de la serie Qwen-Image. La conversión de imagen a imagen/edición de imágenes (I2I) admite hasta 10 imágenes de referencia. También puede decidir automáticamente si generar una imagen estándar o una imagen con canal transparente (alfa) basándose en la descripción del prompt. |
Disponibilidad
El modelo, la URL del endpoint y la clave de API deben pertenecer a la misma región. Las llamadas entre regiones fallarán.
- Seleccione un modelo: Verifique que el modelo esté disponible en su región objetivo.
- Seleccione una URL: Elija la URL del endpoint que coincida con la región de su modelo. Se admiten tanto URLs HTTP como del SDK de DashScope.
- Configurar una clave de API: Obtenga una clave de API para la región y luego configure la clave de API como variable de entorno.
- Instale el SDK: Para realizar llamadas a la API con el SDK, instale el SDK de DashScope.
NotaEl código de ejemplo en este tema aplica a la región de Singapur.
ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
- China (Pekín): de
https://dashscope.aliyuncs.comahttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapur: de
https://dashscope-intl.aliyuncs.comahttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.
Métodos de acceso
La Generación y Edición de Imágenes Qwen ofrece tres métodos de acceso con capacidades de modelo idénticas. Elija el que mejor se adapte a su aplicación:
Método de acceso | Cuándo usar |
|---|---|
Aplicaciones ya construidas sobre el protocolo OpenAI Images o el SDK de OpenAI. Cambie | |
Recomendado. Cobertura completa de funciones, incluyendo tanto URL pública como entrada de imagen Base64. | |
Generación por lotes, o cuando no want mantener una conexión abierta. Envíe una tarea y consulte los resultados con |
Compatible con OpenAI
Si su aplicación ya está construida sobre el protocolo OpenAI Images o el SDK de OpenAI, puede llamar a la Generación y Edición de Imágenes Qwen a través del modo compatible con OpenAI sin cambiar la estructura de su solicitud. Texto a imagen (T2I) e imagen a imagen/edición de imágenes (I2I) comparten el mismo endpoint: omita image para T2I, y proporcione image para I2I.
NotaEl modo compatible con OpenAI es un endpoint sincrónico y sin streaming. La edición de imágenes utiliza el campo de extensión image en /images/generations. No utiliza el formato de carga de archivos multipart del endpoint oficial de OpenAI /images/edits. Aún no se admiten: llamadas asincrónicas, salida en streaming, imágenes parciales, /images/edits, multipart y máscara. Pasar response_format=b64_json no genera un error, pero se ignora y la respuesta aún contiene URLs de imágenes. Para llamadas asincrónicas, utilice Asincrónico de DashScope.
URL
Singapore
Endpoint HTTP: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
EE. UU. (Virginia)
Endpoint HTTP: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
China (Beijing)
Endpoint HTTP: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
China (Hong Kong)
Endpoint HTTP: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Germany (Frankfurt)
Endpoint HTTP: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Japan (Tokyo)
Endpoint HTTP: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url para llamadas SDK: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Parámetros de solicitudEncabezadosContent-Type El tipo de contenido de la solicitud. Debe ser Authorization Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx. Cuerpo de la solicitudA diferencia del protocolo DashScope, el modo compatible con OpenAI coloca todos los parámetros en el nivel superior del cuerpo de la solicitud. No hay anidamiento de model El nombre del modelo. Valores disponibles: prompt El prompt positivo que describe el contenido, estilo y composición de la imagen que want generar o editar. Se admiten tanto chino como inglés. Máximo recomendado: 4,500 tokens. No puede ser una cadena vacía. image La URL o datos codificados en Base64 de la imagen de entrada. Omita este parámetro para texto a imagen (T2I). Proporciónelo para imagen a imagen (I2I), donde la serie qwen-image-2.1 admite 1-10 imágenes, y la serie qwen-image-3.0 admite 1-3 imágenes. Pase una cadena para una sola imagen, o una matriz de cadenas para múltiples imágenes. Cuando se proporcionan múltiples imágenes, el orden se define por la secuencia de la matriz. Nota:
n El número de imágenes de salida. Rango de valores: de 1 a 6. Valor predeterminado: 1. Debe ser un número entero. Un valor de cadena como size La resolución de la imagen de salida en el formato AdvertenciaEl protocolo OpenAI utiliza la letra
negative_prompt El prompt negativo que describe el contenido que no want que aparezca en la imagen. Solo la serie qwen-image-3.0 admite este parámetro. seed La semilla aleatoria. Rango de valores: prompt_extend Indica si se debe habilitar la reescritura inteligente de prompts. Valor predeterminado: prompt_extend_mode El método de reescritura de prompts. Predeterminado:
enable_thinking Habilita el modo de pensamiento. El valor predeterminado es watermark Si se debe agregar una marca de agua. Predeterminado: Nota | |
Parámetros de respuestacreated La marca de tiempo Unix, en segundos, cuando se creó la respuesta. data La lista de resultados generados. Cuando usage El uso de recursos de esta llamada. Solo se devuelve en caso de éxito. Estos son campos de medición de entrada y salida de imágenes, no uso de tokens. error Los detalles del error. Solo se devuelve para solicitudes fallidas. NotaA diferencia del protocolo DashScope, el modo compatible con OpenAI no devuelve | ÉxitoLas URL de las imágenes se conservan solo durante 24 horas y luego se eliminan automáticamente. Guarde las imágenes generadas de inmediato. ErrorSi la solicitud falla, la respuesta contiene un objeto |
SDK
Instale o actualice primero el SDK de OpenAI para Python:
pip install -U openai
ImportanteLa generación de imágenes puede tardar mucho tiempo. Establezca un tiempo de espera de cliente explícito y amplio. Para la salida de múltiples imágenes (un n mayor) o solicitudes concurrentes, comience con 600 segundos para que el cliente no se desconecte prematuramente.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads 'Il Messaggero' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street's end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere.",
size="1024x1024",
n=1,
# All parameters above are official OpenAI parameters. Extension fields such as
# image and prompt_extend go through extra_body. See the I2I example.
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.",
size="1024x1024",
n=1,
extra_body={
# A single image can also be passed as a plain string. Base64 is also accepted:
# data:{MIME_type};base64,{base64_data}
"image": [
"https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
],
"prompt_extend": True,
},
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI, APIStatusError
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
try:
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere.",
)
print(response.data[0].url)
except APIStatusError as exc:
print(f"status_code: {exc.status_code}")
print(f"request_id: {exc.request_id}")
print(exc)
API síncrona de DashScope (recomendada)
HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
EE. UU. (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Parámetros de solicitudEncabezadosContent-Type El tipo de contenido de la solicitud. Debe ser Authorization Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx. Cuerpo de la solicitudmodel El nombre del modelo. Valores disponibles: input El objeto de parámetros de entrada, que contiene los siguientes campos: parameters Parámetros adicionales para controlar la generación de imágenes. | |
Parámetros de respuestaoutput Contiene los resultados de generación del modelo. usage El uso de recursos de esta llamada. Solo se devuelve en caso de éxito. Estos son campos de medición de entrada y salida de imágenes, no uso de tokens. request_id Identificador único de solicitud para rastreo y solución de problemas. code Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error. message Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error. | ÉxitoLos datos de la tarea (estado de la tarea y URL de imágenes) se conservan solo durante 24 horas y luego se eliminan automáticamente. Guarde las imágenes generadas con prontitud. ErrorSi la tarea falla, la respuesta incluye el código de error y el mensaje. Consulte Códigos de error para solucionar problemas. |
SDK
Los siguientes ejemplos demuestran cómo llamar a la API mediante los SDK de Python y Java para la conversión de imagen a imagen y la edición de imágenes (I2I).
import os
import base64
import mimetypes
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
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}"
# [Method 1] Use a public image URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
# [Method 2] Use a Base64-encoded image
# image_url = encode_file("./your_image.png")
response = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen-image-3.0-pro",
messages=[{
"role": "user",
"content": [
{"image": image_url},
{"text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop."}
]
}],
prompt_extend=True
)
print(response)
if response.status_code == 200:
url = response.output.choices[0].message.content[0]["image"]
print(f"Generated image URL: {url}")
else:
print(f"Error: {response.code} - {response.message}")
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
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.utils.Constants;
public class ImageEditExample {
public static void main(String[] args) {
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
// [Method 1] Use a public image URL
String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";
// [Method 2] Use a Base64-encoded image
// String imageUrl = encodeFile("/path/to/your/image.png");
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", imageUrl),
Collections.singletonMap("text", "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.")
))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-image-3.0-pro")
.messages(Arrays.asList(userMessage))
.parameter("prompt_extend", true)
.build();
try {
MultiModalConversationResult result = conv.call(param);
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
}
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) {
throw new IllegalArgumentException("File does not exist: " + filePath);
}
String mimeType = null;
try {
mimeType = Files.probeContentType(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot detect file type: " + filePath);
}
if (mimeType == null || !mimeType.startsWith("image/")) {
throw new IllegalArgumentException("Unsupported or unrecognized image format");
}
byte[] fileBytes = null;
try {
fileBytes = Files.readAllBytes(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot read file content: " + filePath);
}
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
}
API asíncrona de DashScope
Además de la llamada sincrónica descrita anteriormente, la Generación y Edición de Imágenes Qwen también admite llamadas asincrónicas. La API asincrónica comparte la misma estructura de parámetros de solicitud que la API sincrónica. Solo necesita agregar el encabezado X-DashScope-Async: enable. Después de que el servicio acepte la solicitud, devuelve un ID de tarea (task_id), que luego utiliza para consultar la API de consulta y obtener el resultado final.
ImportanteEl endpoint para la API asincrónica difiere del de la API sincrónica. Utilice los endpoints de esta sección en lugar del endpoint sincrónico.
HTTP
Las llamadas asíncronas utilizan un flujo de trabajo de dos pasos:
- Crear una tarea para obtener un ID de tarea: Envíe una solicitud para crear una tarea. La respuesta contiene un ID de tarea (task_id).
- Consultar resultados mediante el ID de tarea: Utilice el task_id para consultar el estado de la tarea hasta que esta se complete y se devuelva la URL de la imagen.
Paso 1: Crear una tarea para obtener un ID de tarea
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
EE. UU. (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Parámetros de solicitudEncabezadosContent-Type El tipo de contenido de la solicitud. Debe ser Authorization Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx. X-DashScope-Async Habilita el procesamiento asincrónico. Debe ser ImportanteSi falta este encabezado de solicitud, se devuelve el error "current user api does not support synchronous calls". Cuerpo de la solicitudmodel El nombre del modelo. Valores disponibles: input El objeto de parámetros de entrada, que contiene los siguientes campos: parameters Parámetros adicionales para controlar la generación de imágenes. | |
Parámetros de respuestaoutput La información de aceptación de la tarea. request_id Identificador único de solicitud para rastreo y solución de problemas. code Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error. | Respuesta exitosaGuarde el Respuesta de errorError en la creación de la tarea. Consulte Códigos de error. |
Paso 2: Consultar resultados mediante el ID de tarea
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
EE. UU. (Virginia)
GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Beijing)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Hong Kong)
GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}
Germany (Frankfurt)
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Japan (Tokyo)
GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Debe utilizar la misma región, espacio de trabajo y clave de API que cuando creó la tarea. No se admiten consultas entre regiones o entre espacios de trabajo.
Parámetros de solicitudEncabezadosAuthorization Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx. Parámetros de ruta de URLtask_id El ID de la tarea. | Consultar resultado de la tareaReemplace |
Parámetros de respuestaoutput La información de salida de la tarea. usage El uso de recursos de esta llamada. Solo se devuelve en caso de éxito. Estos son campos de medición de entrada y salida de imágenes, no uso de tokens. request_id Identificador único de solicitud para rastreo y solución de problemas. code Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error. message Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error. | Tarea exitosaLos datos de la tarea (estado de la tarea y URL de imágenes) se conservan solo durante 24 horas y luego se eliminan automáticamente. Guarde las imágenes generadas con prontitud. Tarea fallidaCuando una tarea falla, |
Códigos de error
Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.