Skip to main content

Referencia de la API de Generación y Edición de Imágenes Qwen

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:

  • Texto a imagen (T2I): El total de píxeles debe estar entre 512*512 y 2048*2048.

  • Imagen a imagen (I2I): El total de píxeles debe estar entre 512*512 y 2048*2048.

  • Predeterminado: Cuando no se especifica size, el modelo recomienda automáticamente una resolución basada en el prompt.

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.
El código de ejemplo en este tema aplica a la región de Singapur.
Alibaba 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.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de https://dashscope-intl.aliyuncs.com a https://{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

Compatible con OpenAI

Aplicaciones ya construidas sobre el protocolo OpenAI Images o el SDK de OpenAI. Cambie base_url y model para migrar. Solo llamadas sincrónicas. La entrada de imagen admite tanto URL pública como Base64.

Síncrono de DashScope

Recomendado. Cobertura completa de funciones, incluyendo tanto URL pública como entrada de imagen Base64.

Asincrónico de DashScope

Generación por lotes, o cuando no want mantener una conexión abierta. Envíe una tarea y consulte los resultados con task_id.

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.
El 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
  • EE. UU. (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
Endpoint HTTP: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generationsbase_url para llamadas SDK: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Parámetros de solicitud

Encabezados

Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.

Cuerpo de la solicitud

A 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 input ni de parameters.model string (Obligatorio)El nombre del modelo. Valores disponibles: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro y qwen-image-2.1-turbo.prompt string (Obligatorio)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 string o array (Opcional)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: null y los arreglos vacíos se rechazan con un error 400.Requisitos de imagen:
  • Formato de imagen: JPG, JPEG, PNG, BMP, TIFF, WEBP y GIF.
  • Resolución de imagen: El ancho y el alto deben estar entre 1 y 8000 píxeles; exceder esto devuelve un error 400. Para obtener mejores resultados, utilice de 384 a 2048 píxeles.
  • Relación de aspecto: La proporción del lado más largo respecto al lado más corto no debe exceder 10:1.
  • Tamaño de imagen: Hasta 10 MB.
Formatos de entrada admitidos
  1. URL pública: Se admiten los protocolos HTTP y HTTPS.
  2. Codificación Base64: El formato es data:{MIME_type};base64,{base64_data}.
n integer (Opcional)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 "1" devuelve un error 400.size string (Opcional)La resolución de la imagen de salida en el formato widthxheight, por ejemplo "1024x1024". También puede pasar auto. Si no se especifica, el modelo recomienda automáticamente una resolución basada en el prompt.
El protocolo OpenAI utiliza la letra x como separador (1024x1024), no el asterisco * utilizado por el protocolo DashScope (1024*1024). Actualice este valor al migrar desde DashScope.
  • Texto a imagen (T2I): Área de píxeles de 512x512 a 2048x2048. Relación de aspecto: de 1:8 a 8:1.
  • Imagen a imagen (I2I): Área de píxeles de 512x512 a 2048x2048. Relación de aspecto: de 1:8 a 8:1.
negative_prompt string (Opcional)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 integer (Opcional)La semilla aleatoria. Rango de valores: [0, 2147483647]. Si se omite, el servicio genera una semilla aleatoria. Utilice una semilla fija para obtener resultados reproducibles.prompt_extend boolean (Opcional)Indica si se debe habilitar la reescritura inteligente de prompts. Valor predeterminado: true (recomendado). Cuando está habilitado, el modelo optimiza el prompt positivo utilizando el método especificado por prompt_extend_mode, lo que mejora significativamente los resultados para descripciones simples.prompt_extend_mode string (Opcional)El método de reescritura de prompts. Predeterminado: direct. Opciones:
  • direct: Mejora directa de prompts (DPE), adecuada para la mayoría de los escenarios. Compatible tanto con T2I como con I2I.
  • agent: Mejora de Prompt de Agente (APE), proporciona una reescritura más refinada. Solo admite texto a imagen (T2I). Pasar agent para imagen a imagen (I2I) devolverá un error 400.
enable_thinking boolean (Opcional)Habilita el modo de pensamiento. El valor predeterminado es true. Esto mejora el razonamiento del modelo para aumentar la calidad de la imagen, pero incrementa el tiempo de generación. Requiere prompt_extend=true. Admitido para T2I directo, I2I directo y T2I de agente. No admitido para I2I de agente.watermark boolean (Opcional)Si se debe agregar una marca de agua. Predeterminado: false.
image, negative_prompt, seed, prompt_extend, prompt_extend_mode, enable_thinking y watermark son campos de extensión de Model Studio, no parámetros oficiales de OpenAI. Para solicitudes HTTP sin procesar, colóquelos en el nivel superior del cuerpo de la solicitud. Al utilizar un SDK de OpenAI, páselos a través de extra_body.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "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,
    "prompt_extend": true
}'

Parámetros de respuesta

created integerLa marca de tiempo Unix, en segundos, cuando se creó la respuesta.data arrayLa lista de resultados generados. Cuando n es mayor que 1, el arreglo contiene múltiples elementos.

Propiedades

url stringLa URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.
usage objectEl 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.

Propiedades

  • Serie qwen-image-3.0
  • Serie qwen-image-2.1
output_width integerEl ancho de la imagen de salida final en píxeles.output_height integerLa altura de la imagen de salida final en píxeles.input_image_count integerEl número de imágenes de entrada en la solicitud. Devuelve 0 para texto a imagen (T2I) y el recuento real para imagen a imagen (I2I).input_image_type stringEl nivel de facturación de la imagen de entrada. Determinado por el área de píxeles de la resolución de salida: qima_input_1k si el área es ≤ 2,250,000, o qima_input_2k si el área es > 2,250,000.output_image_count integerEl número real de imágenes de salida devueltas.output_image_type stringEl nivel de facturación de la imagen de salida. Determinado por el área de píxeles de la resolución de salida: qima_output_1k si el área es ≤ 2,250,000, o qima_output_2k si el área es > 2,250,000.
error objectLos detalles del error. Solo se devuelve para solicitudes fallidas.

Propiedades

message stringMensaje de error detallado.type stringEl tipo de error, como invalid_request_error.param stringEl nombre del parámetro que causó el error, o null cuando el error no puede atribuirse a un parámetro específico.code stringCódigo de error. Consulte Códigos de error.
A diferencia del protocolo DashScope, el modo compatible con OpenAI no devuelve request_id en el cuerpo de la respuesta. El identificador único de la solicitud se devuelve en el encabezado de respuesta HTTP x-request-id. Con el SDK de Python de OpenAI, lea response._request_id en caso de éxito y APIStatusError.request_id en caso de fallo. Incluya este identificador al reportar un problema.
  • Éxito
  • Error
Las URL de las imágenes se conservan solo durante 24 horas y luego se eliminan automáticamente. Guarde las imágenes generadas de inmediato.
{
    "created": 1788339600,
    "data": [
        {
            "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
        }
    ],
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    }
}

SDK

Instale o actualice primero el SDK de OpenAI para Python:
pip install -U openai
La 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}")

API síncrona de DashScope (recomendada)

HTTP

  • Singapore
  • EE. UU. (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Parámetros de solicitud

Encabezados
Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.
Cuerpo de la solicitud
model string (Obligatorio)El nombre del modelo. Valores disponibles: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro y qwen-image-2.1-turbo.input object (Obligatorio)El objeto de parámetros de entrada, que contiene los siguientes campos:

Propiedades

messages array (Obligatorio)La matriz de contenido de la solicitud. Solo se admiten conversaciones de una sola ronda, por lo que la matriz debe contener exactamente un objeto con las propiedades role y content.

Propiedades

rolestring (Obligatorio)El rol del remitente del mensaje. Debe establecerse en user.contentarray (Obligatorio)El arreglo de contenido del mensaje, con diferentes combinaciones según el caso de uso:
  • Texto a imagen (T2I): Contiene solo un objeto {"text": "..."}.
  • Imagen a imagen (I2I): la serie qwen-image-2.1 contiene 1-10 objetos {"image": "..."}, la serie qwen-image-3.0 contiene 1-3, y 1 objeto {"text": "..."}.

Propiedades

image string (Requerido para I2I)La URL o datos codificados en Base64 de la imagen de entrada. En escenarios I2I, la serie qwen-image-2.1 admite 1-10 imágenes, y la serie qwen-image-3.0 admite 1-3 imágenes. Cuando se proporcionan múltiples imágenes, el orden se define por la secuencia de la matriz.Requisitos de imagen:
  • Formato de imagen: JPG, JPEG, PNG, BMP, TIFF, WEBP y GIF.
  • Resolución de imagen: El ancho y el alto deben estar entre 1 y 8000 píxeles; exceder esto devuelve un error 400. Para obtener mejores resultados, utilice de 384 a 2048 píxeles.
  • Relación de aspecto: La proporción del lado más largo respecto al lado más corto no debe exceder 10:1.
  • Tamaño de imagen: Hasta 10 MB.
Formatos de entrada admitidos
  1. URL pública: Se admiten los protocolos HTTP y HTTPS.
  2. Codificación Base64: El formato es data:{MIME_type};base64,{base64_data}.
textstring(Obligatorio)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.Nota: Solo se permite un objeto de texto. Omitirlo o proporcionar múltiples objetos de texto resultará en un error.
parameters object (Opcional)Parámetros adicionales para controlar la generación de imágenes.

Propiedades

prompt_extend boolean (Opcional)Indica si se debe habilitar la reescritura inteligente de prompts. Valor predeterminado: true (recomendado). Cuando está habilitado, el modelo optimiza el prompt positivo utilizando el método especificado por prompt_extend_mode, lo que mejora significativamente los resultados para descripciones simples.prompt_extend_mode string (Opcional)El método de reescritura de prompts. Predeterminado: direct. Opciones:
  • direct: Mejora directa de prompts (DPE), adecuada para la mayoría de los escenarios. Compatible tanto con T2I como con I2I.
  • agent: Mejora de Prompt de Agente (APE), proporciona una reescritura más refinada. Solo admite texto a imagen (T2I). Pasar agent para imagen a imagen (I2I) devolverá un error 400.
enable_thinking boolean (Opcional)Habilita el modo de pensamiento. El valor predeterminado es true. Esto mejora el razonamiento del modelo para aumentar la calidad de la imagen, pero incrementa el tiempo de generación. Requiere prompt_extend=true. Admitido para T2I directo, I2I directo y T2I de agente. No admitido para I2I de agente.n integer (Opcional)El número de imágenes de salida. Rango de valores: de 1 a 6. Predeterminado: 1.size string (Opcional)La resolución de la imagen de salida en el formato width*height, por ejemplo "1024*1024". Si no se especifica, el modelo recomienda automáticamente una resolución basada en el prompt.
  • Texto a imagen (T2I): Área de píxeles de 512*512 a 2048*2048. Relación de aspecto: de 1:8 a 8:1.
  • Imagen a imagen (I2I): Área de píxeles de 512*512 a 2048*2048. Relación de aspecto: de 1:8 a 8:1.
negative_prompt string (Opcional)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 integer (Opcional)La semilla aleatoria. Rango de valores: [0, 2147483647]. Si se omite, el servicio genera una semilla aleatoria. Utilice una semilla fija para obtener resultados reproducibles.watermark boolean (Opcional)Si se debe agregar una marca de agua. Predeterminado: false.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "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."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'

Parámetros de respuesta

output objectContiene los resultados de generación del modelo.

Propiedades

rewrite_status stringEl estado de reescritura del prompt. El valor depende de si la reescritura se habilitó en la solicitud y del resultado de dicha reescritura.choices arrayLa lista de opciones de resultados.

Propiedades

finish_reason stringLa razón por la cual la tarea se detuvo. El valor es stop cuando la tarea se completa normalmente.message objectEl mensaje devuelto por el modelo.

Propiedades

rolestringEl rol del mensaje. Fijo como assistant.contentarrayEl contenido del mensaje que contiene la información de la imagen generada.

Propiedades

imagen stringLa URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.
usage objectEl 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.

Propiedades

  • Serie qwen-image-3.0
  • Serie qwen-image-2.1
output_width integerEl ancho de la imagen de salida final en píxeles.output_height integerLa altura de la imagen de salida final en píxeles.input_image_count integerEl número de imágenes de entrada en la solicitud. Devuelve 0 para texto a imagen (T2I) y el recuento real para imagen a imagen (I2I).input_image_type stringEl nivel de facturación de la imagen de entrada. Determinado por el área de píxeles de la resolución de salida: qima_input_1k si el área es ≤ 2,250,000, o qima_input_2k si el área es > 2,250,000.output_image_count integerEl número real de imágenes de salida devueltas.output_image_type stringEl nivel de facturación de la imagen de salida. Determinado por el área de píxeles de la resolución de salida: qima_output_1k si el área es ≤ 2,250,000, o qima_output_2k si el área es > 2,250,000.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
  • Éxito
  • Error
Los 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.
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 1,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

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).
Python
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}")

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.
El 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:
  1. 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).
  2. 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
  • EE. UU. (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Parámetros de solicitud
Encabezados
Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.X-DashScope-Async string (Requerido)Habilita el procesamiento asincrónico. Debe ser enable. El endpoint de esta sección acepta únicamente solicitudes asincrónicas y no admite llamadas sincrónicas.
Si falta este encabezado de solicitud, se devuelve el error "current user api does not support synchronous calls".
Cuerpo de la solicitud
model string (Obligatorio)El nombre del modelo. Valores disponibles: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro y qwen-image-2.1-turbo.input object (Obligatorio)El objeto de parámetros de entrada, que contiene los siguientes campos:

Propiedades

messages array (Obligatorio)La matriz de contenido de la solicitud. Solo se admiten conversaciones de una sola ronda, por lo que la matriz debe contener exactamente un objeto con las propiedades role y content.

Propiedades

rolestring (Obligatorio)El rol del remitente del mensaje. Debe establecerse en user.contentarray (Obligatorio)El arreglo de contenido del mensaje, con diferentes combinaciones según el caso de uso:
  • Texto a imagen (T2I): Contiene solo un objeto {"text": "..."}.
  • Imagen a imagen (I2I): la serie qwen-image-2.1 contiene 1-10 objetos {"image": "..."}, la serie qwen-image-3.0 contiene 1-3, y 1 objeto {"text": "..."}.

Propiedades

image string (Requerido para I2I)La URL o datos codificados en Base64 de la imagen de entrada. En escenarios I2I, la serie qwen-image-2.1 admite 1-10 imágenes, y la serie qwen-image-3.0 admite 1-3 imágenes. Cuando se proporcionan múltiples imágenes, el orden se define por la secuencia de la matriz.Requisitos de imagen:
  • Formato de imagen: JPG, JPEG, PNG, BMP, TIFF, WEBP y GIF.
  • Resolución de imagen: El ancho y el alto deben estar entre 1 y 8000 píxeles; exceder esto devuelve un error 400. Para obtener mejores resultados, utilice de 384 a 2048 píxeles.
  • Relación de aspecto: La proporción del lado más largo respecto al lado más corto no debe exceder 10:1.
  • Tamaño de imagen: Hasta 10 MB.
Formatos de entrada admitidos
  1. URL pública: Se admiten los protocolos HTTP y HTTPS.
  2. Codificación Base64: El formato es data:{MIME_type};base64,{base64_data}.
textstring(Obligatorio)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.Nota: Solo se permite un objeto de texto. Omitirlo o proporcionar múltiples objetos de texto resultará en un error.
parameters object (Opcional)Parámetros adicionales para controlar la generación de imágenes.

Propiedades

prompt_extend boolean (Opcional)Indica si se debe habilitar la reescritura inteligente de prompts. Valor predeterminado: true (recomendado). Cuando está habilitado, el modelo optimiza el prompt positivo utilizando el método especificado por prompt_extend_mode, lo que mejora significativamente los resultados para descripciones simples.prompt_extend_mode string (Opcional)El método de reescritura de prompts. Predeterminado: direct. Opciones:
  • direct: Mejora directa de prompts (DPE), adecuada para la mayoría de los escenarios. Compatible tanto con T2I como con I2I.
  • agent: Mejora de Prompt de Agente (APE), proporciona una reescritura más refinada. Solo admite texto a imagen (T2I). Pasar agent para imagen a imagen (I2I) devolverá un error 400.
enable_thinking boolean (Opcional)Habilita el modo de pensamiento. El valor predeterminado es true. Esto mejora el razonamiento del modelo para aumentar la calidad de la imagen, pero incrementa el tiempo de generación. Requiere prompt_extend=true. Admitido para T2I directo, I2I directo y T2I de agente. No admitido para I2I de agente.n integer (Opcional)El número de imágenes de salida. Rango de valores: de 1 a 6. Predeterminado: 1.size string (Opcional)La resolución de la imagen de salida en el formato width*height, por ejemplo "1024*1024". Si no se especifica, el modelo recomienda automáticamente una resolución basada en el prompt.
  • Texto a imagen (T2I): Área de píxeles de 512*512 a 2048*2048. Relación de aspecto: de 1:8 a 8:1.
  • Imagen a imagen (I2I): Área de píxeles de 512*512 a 2048*2048. Relación de aspecto: de 1:8 a 8:1.
negative_prompt string (Opcional)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 integer (Opcional)La semilla aleatoria. Rango de valores: [0, 2147483647]. Si se omite, el servicio genera una semilla aleatoria. Utilice una semilla fija para obtener resultados reproducibles.watermark boolean (Opcional)Si se debe agregar una marca de agua. Predeterminado: false.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "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."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
Parámetros de respuesta
output objectLa información de aceptación de la tarea.

Propiedades

task_id stringEl ID de tarea asíncrona, utilizado para consultar el estado y el resultado de la tarea. Asegúrese de guardarlo.task_status stringEl estado de la tarea. Generalmente PENDING cuando se envía la tarea, lo que indica únicamente que la tarea ha sido aceptada, no que la imagen haya sido generada.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
  • Respuesta exitosa
  • Respuesta de error
Guarde el task_id para consultar el estado y el resultado de la tarea.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Paso 2: Consultar resultados mediante el ID de tarea

  • Singapore
  • EE. UU. (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-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 solicitud
Encabezados
Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.
Parámetros de ruta de URL
task_id string (Obligatorio)El ID de la tarea.
  • Consultar resultado de la tarea
Reemplace {task_id} con el valor task_id devuelto por la llamada a la API anterior. El task_id es válido para consultas durante 24 horas. Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Parámetros de respuesta
output objectLa información de salida de la tarea.

Propiedades

task_id stringEl ID de la tarea. Válido para consultas durante 24 horas.task_status stringEl estado de la tarea.

Valores de enumeración

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: La tarea no existe o se desconoce su estado.
Transiciones de estado durante el sondeo:
  • PENDING → RUNNING → SUCCEEDED o FAILED.
  • El estado inicial de la consulta suele ser PENDING o RUNNING.
  • Cuando el estado cambia a SUCCEEDED, la respuesta contiene la URL de la imagen generada.
  • Si el estado es FAILED, revise el mensaje de error y reintente la tarea.
submit_time stringLa hora en que se envió la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringLa hora en que se ejecutó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.end_time stringLa hora en que se completó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.rewrite_status stringEl estado de reescritura del prompt. El valor depende de si la reescritura se habilitó en la solicitud y del resultado de dicha reescritura.choices arrayLa lista de opciones de resultados.

Propiedades

finish_reason stringLa razón por la cual la tarea se detuvo. El valor es stop cuando la tarea se completa normalmente.message objectEl mensaje devuelto por el modelo.

Propiedades

rolestringEl rol del mensaje. Fijo como assistant.contentarrayEl contenido del mensaje que contiene la información de la imagen generada.

Propiedades

imagen stringLa URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.
usage objectEl 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.

Propiedades

  • Serie qwen-image-3.0
  • Serie qwen-image-2.1
output_width integerEl ancho de la imagen de salida final en píxeles.output_height integerLa altura de la imagen de salida final en píxeles.input_image_count integerEl número de imágenes de entrada en la solicitud. Devuelve 0 para texto a imagen (T2I) y el recuento real para imagen a imagen (I2I).input_image_type stringEl nivel de facturación de la imagen de entrada. Determinado por el área de píxeles de la resolución de salida: qima_input_1k si el área es ≤ 2,250,000, o qima_input_2k si el área es > 2,250,000.output_image_count integerEl número real de imágenes de salida devueltas.output_image_type stringEl nivel de facturación de la imagen de salida. Determinado por el área de píxeles de la resolución de salida: qima_output_1k si el área es ≤ 2,250,000, o qima_output_2k si el área es > 2,250,000.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
  • Tarea exitosa
  • Tarea fallida
Los 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.
{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-07 15:50:14.837",
        "scheduled_time": "2026-08-07 15:50:14.884",
        "end_time": "2026-08-07 15:50:33.607",
        "rewrite_status": "not_use",
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
}

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.