Todos los productos
Search
Centro de documentos

Alibaba Cloud Model Studio:Referencia de la API de Generación y Edición de Imágenes Qwen

Última actualización: Oct 12, 2026

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.

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.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.

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 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.

AdvertenciaEl 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.

Notaimage, 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
}'
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": "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. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere.",
    "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png",
    "size": "1024x1024",
    "n": 1,
    "prompt_extend": true
}'

Parámetros de respuesta

created integer

La marca de tiempo Unix, en segundos, cuando se creó la respuesta.

data array

La lista de resultados generados. Cuando n es mayor que 1, el arreglo contiene múltiples elementos.

Propiedades

url string

La URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.

usage object

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.

Propiedades

Serie qwen-image-3.0

output_width integer

El ancho de la imagen de salida final en píxeles.

output_height integer

La altura de la imagen de salida final en píxeles.

input_image_count integer

El 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 string

El 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 integer

El número real de imágenes de salida devueltas.

output_image_type string

El 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.

Serie qwen-image-2.1

image_count integer

El número de imágenes generadas por el modelo.

width integer

El ancho de la imagen generada en píxeles.

height integer

La altura de la imagen generada en píxeles.

error object

Los detalles del error. Solo se devuelve para solicitudes fallidas.

Propiedades

message string

Mensaje de error detallado.

type string

El tipo de error, como invalid_request_error.

param string

El nombre del parámetro que causó el error, o null cuando el error no puede atribuirse a un parámetro específico.

code string

Código de error. Consulte Códigos de error.

NotaA 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

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"
    }
}
{
    "created": 1788339600,
    "data": [
        {
            "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
        }
    ],
    "usage": {
        "image_count": 1,
        "width": 1024,
        "height": 1024
    }
}

Error

Si la solicitud falla, la respuesta contiene un objeto error cuyos campos code y message identifican la causa. Consulte Códigos de error para solucionar problemas.

{
    "error": {
        "message": "Field 'prompt' is required",
        "type": "invalid_request_error",
        "param": null,
        "code": "InvalidParameter"
    }
}

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 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
    }
}'
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": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "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. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'

Parámetros de respuesta

output object

Contiene los resultados de generación del modelo.

Propiedades

rewrite_status string

El estado de reescritura del prompt. El valor depende de si la reescritura se habilitó en la solicitud y del resultado de dicha reescritura.

choices array

La lista de opciones de resultados.

Propiedades

finish_reason string

La razón por la cual la tarea se detuvo. El valor es stop cuando la tarea se completa normalmente.

message object

El mensaje devuelto por el modelo.

Propiedades

rolestring

El rol del mensaje. Fijo como assistant.

contentarray

El contenido del mensaje que contiene la información de la imagen generada.

Propiedades

imagen string

La URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.

usage object

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.

Propiedades

Serie qwen-image-3.0

output_width integer

El ancho de la imagen de salida final en píxeles.

output_height integer

La altura de la imagen de salida final en píxeles.

input_image_count integer

El 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 string

El 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 integer

El número real de imágenes de salida devueltas.

output_image_type string

El 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.

Serie qwen-image-2.1

image_count integer

El número de imágenes generadas por el modelo.

width integer

El ancho de la imagen generada en píxeles.

height integer

La altura de la imagen generada en píxeles.

request_id string

Identificador único de solicitud para rastreo y solución de problemas.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Éxito

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"
}
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "image_count": 1,
        "width": 1024,
        "height": 1024
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

Error

Si la tarea falla, la respuesta incluye el código de error y el mensaje. Consulte Códigos de error para solucionar problemas.

{
    "request_id": "31f808fd-8eef-9004-xxxxx",
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided."
}

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:

  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

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 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.

ImportanteSi 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
    }
}'
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": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "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. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
Parámetros de respuesta

output object

La información de aceptación de la tarea.

Propiedades

task_id string

El ID de tarea asíncrona, utilizado para consultar el estado y el resultado de la tarea. Asegúrese de guardarlo.

task_status string

El 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 string

Identificador único de solicitud para rastreo y solución de problemas.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Respuesta exitosa

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"
}

Respuesta de error

Error en la creación de la tarea. Consulte Códigos de error.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

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 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 object

La información de salida de la tarea.

Propiedades

task_id string

El ID de la tarea. Válido para consultas durante 24 horas.

task_status string

El 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 string

La 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 string

La 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 string

La 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 string

El estado de reescritura del prompt. El valor depende de si la reescritura se habilitó en la solicitud y del resultado de dicha reescritura.

choices array

La lista de opciones de resultados.

Propiedades

finish_reason string

La razón por la cual la tarea se detuvo. El valor es stop cuando la tarea se completa normalmente.

message object

El mensaje devuelto por el modelo.

Propiedades

rolestring

El rol del mensaje. Fijo como assistant.

contentarray

El contenido del mensaje que contiene la información de la imagen generada.

Propiedades

imagen string

La URL de la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen de inmediato.

usage object

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.

Propiedades

Serie qwen-image-3.0

output_width integer

El ancho de la imagen de salida final en píxeles.

output_height integer

La altura de la imagen de salida final en píxeles.

input_image_count integer

El 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 string

El 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 integer

El número real de imágenes de salida devueltas.

output_image_type string

El 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.

Serie qwen-image-2.1

image_count integer

El número de imágenes generadas por el modelo.

width integer

El ancho de la imagen generada en píxeles.

height integer

La altura de la imagen generada en píxeles.

request_id string

Identificador único de solicitud para rastreo y solución de problemas.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Tarea exitosa

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"
}
{
    "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": {
        "image_count": 1,
        "width": 1024,
        "height": 1024
    },
    "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
}

Tarea fallida

Cuando una tarea falla, task_status es FAILED con un código de error y un mensaje. Consulte Códigos de error.

{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "An internal error has occurred."
    },
    "request_id": "31f808fd-8eef-9004-xxxxx"
}

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.