Referencia de la API Z-Image de texto a imagen - Alibaba Cloud Model Studio

Un modelo ligero de texto a imagen para generación rápida, con renderizado de texto en chino e inglés, y resoluciones flexibles.

Pruébelo en línea: (Singapore | Beijing) | Blog técnico

Ejemplos

Prompt de entrada	Imagen de salida
Fotografía de una joven elegante con cabello negro corto, posando con seguridad frente a un vibrante mural de estilo caricaturesco. Viste un conjunto completamente negro: una chaqueta bomber acolchada con cuello de volantes, pantalones cortos cargo, medias de red y botas Doc Martens negras de suela gruesa, con una cadena dorada colgando de su cintura. El fondo presenta cuatro paneles coloridos al estilo cómic: uno dice “GRAND STAGE” e incluye zapatillas deportivas y una botella de Gatorade; otro muestra zapatillas Nike verdes y una rebanada de pizza; el tercero dice “HARAJUKU st” con zapatos flotantes; y el cuarto muestra un ratón azul montando una patineta con el texto “Takeshita WELCOME.”. Los colores brillantes predominantes incluyen amarillo, verde azulado, naranja, rosa y verde. Globos de diálogo, patrones de semitonos y personajes lúdicos realzan la estética de arte callejero urbano. La luz diurna ilumina uniformemente la escena, y el suelo bajo sus pies es un pavimento de baldosas blancas. Retrato de cuerpo entero, composición centrada, postura ligeramente inclinada, contacto visual directo con la cámara. Alto nivel de detalle, enfoque nítido, encuadre dinámico.

Prompt de entrada

Imagen de salida

Fotografía de una joven elegante con cabello negro corto, posando con seguridad frente a un vibrante mural de estilo caricaturesco. Viste un conjunto completamente negro: una chaqueta bomber acolchada con cuello de volantes, pantalones cortos cargo, medias de red y botas Doc Martens negras de suela gruesa, con una cadena dorada colgando de su cintura. El fondo presenta cuatro paneles coloridos al estilo cómic: uno dice “GRAND STAGE” e incluye zapatillas deportivas y una botella de Gatorade; otro muestra zapatillas Nike verdes y una rebanada de pizza; el tercero dice “HARAJUKU st” con zapatos flotantes; y el cuarto muestra un ratón azul montando una patineta con el texto “Takeshita WELCOME.”. Los colores brillantes predominantes incluyen amarillo, verde azulado, naranja, rosa y verde. Globos de diálogo, patrones de semitonos y personajes lúdicos realzan la estética de arte callejero urbano. La luz diurna ilumina uniformemente la escena, y el suelo bajo sus pies es un pavimento de baldosas blancas. Retrato de cuerpo entero, composición centrada, postura ligeramente inclinada, contacto visual directo con la cámara. Alto nivel de detalle, enfoque nítido, encuadre dinámico.

b16c8008-83c1-4c80-ae22-786a2299bec3-1-convertido-de-png

Resumen de modelos

Nombre del modelo	Descripción	Especificaciones de la imagen de salida
z-image-turbo	Un modelo ligero y rápido de generación de imágenes	Resolución de imagen: de 512×512 a 2048×2048 píxeles. Consulte las resoluciones recomendadas en la configuración del parámetro size. Formato de imagen: png Número de imágenes: Fijo en 1.

Nombre del modelo

Descripción

Especificaciones de la imagen de salida

z-image-turbo

Un modelo ligero y rápido de generación de imágenes

Resolución de imagen: de 512×512 a 2048×2048 píxeles. Consulte las resoluciones recomendadas en la configuración del parámetro size.

Formato de imagen: png

Número de imágenes: Fijo en 1.

NotaConsulte la Lista de modelos para verificar la compatibilidad regional antes de realizar la llamada.

Requisitos previos

Cree una clave API y configure la clave API como una variable de entorno.

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.

Llamada HTTP síncrona

Singapur:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Beijing: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 de solicitud

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)

Nombre del modelo: z-image-turbo.

input object (Obligatorio)

Contenido de entrada.

Propiedades

messages array (Obligatorio)

Matriz de contenido de la solicitud. Solo turno único — pase un conjunto de rol y contenido. No se admiten múltiples turnos.

Propiedades

rolestring (Obligatorio)

Rol del mensaje: user.

contentarray (Obligatorio)

Matriz de contenido del mensaje. Debe contener un objeto de texto.

Propiedades

textstring(Obligatorio)

Prompt positivo que describe el contenido, estilo y composición deseados.

Admite chino e inglés. Máximo 800 caracteres (cada carácter, letra, número o símbolo cuenta como uno). Los caracteres adicionales se truncan.

Ejemplo: Un gato naranja sentado con una expresión feliz, animado y tierno, realista y preciso.

Nota: Solo se admite un objeto de texto. Pasar cero o múltiples objetos de texto devuelve un error.

parameters object (Opcional)

Parámetros de generación de imagen.

Propiedades

size string (Opcional)

Resolución de la imagen de salida en formato ancho×alto.

Predeterminado: 1024*1536
Rango: 512×512 a 2048×2048
Recomendado: 1024×1024 a 1536×1536

Ejemplo: 1024*1536.

Resoluciones recomendadas para un total de 1024*1024 píxeles:

1:1: 1024*1024
2:3: 832*1248
3:2: 1248*832
3:4: 864*1152
4:3: 1152*864
7:9: 896*1152
9:7: 1152*896
9:16: 720*1280
9:21: 576*1344
16:9: 1280*720
21:9: 1344*576

Resoluciones recomendadas para un total de 1280*1280 píxeles:

1:1: 1280*1280
2:3: 1024*1536
3:2: 1536*1024
3:4: 1104*1472
4:3: 1472*1104
7:9: 1120*1440
9:7: 1440*1120
9:16: 864*1536
9:21: 720*1680
16:9: 1536*864
21:9: 1680*720

Resoluciones recomendadas para un total de 1536*1536 píxeles:

1:1: 1536*1536
2:3: 1248*1872
3:2: 1872*1248
3:4: 1296*1728
4:3: 1728*1296
7:9: 1344*1728
9:7: 1728*1344
9:16: 1152*2048
9:21: 864*2016
16:9: 2048*1152
21:9: 2016*864

prompt_extend bool (Opcional)

ImportanteActivar prompt_extend aumenta el costo. Consulte Precios de modelos para más detalles.

Habilite la reescritura inteligente de prompts mediante optimización LLM y salida de razonamiento.

false (predeterminado): Devuelve la imagen y el prompt original
true: Devuelve la imagen, el prompt optimizado y el razonamiento

seed integer (opcional)

Semilla de número aleatorio. Rango válido: [0,2147483647].

Usar la misma seed produce resultados similares. Si se omite, el algoritmo utiliza una semilla aleatoria.

Nota: La generación de imágenes es probabilística. Incluso con la misma seed, los resultados pueden variar.

Texto a imagen

Este ejemplo devuelve una imagen directamente para obtener una respuesta más rápida. Para habilitar la reescritura inteligente, configure prompt_extend=true; el sistema devolverá el prompt optimizado, el razonamiento y la imagen (lo que aumenta el tiempo de respuesta).

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": "z-image-turbo",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1024*1024"
    }
}'

Parámetros de respuesta

output object

Salida del modelo.

Propiedades

choices array

Contenido de salida del modelo. La matriz contiene un elemento.

Propiedades

finish_reason string

Motivo de finalización. El valor stop indica éxito.

message object

Mensaje de respuesta del modelo.

Propiedades

rolestring

Rol del mensaje. El valor es assistant.

contentarray

Propiedades

imagen string

URL de la imagen generada (PNG). Válida por 24 horas — descárguela pronto.

text string

Esto devuelve el prompt de entrada (prompt_extend=false) o el prompt reescrito (prompt_extend=true).

reasoning_content string

Proceso de razonamiento del modelo. Solo se devuelve cuando prompt_extend=true.

usage object

Esto incluye estadísticas de uso solo para generaciones exitosas.

Propiedades

width integer

Ancho de la imagen generada (píxeles).

height integer

Altura de la imagen generada (píxeles).

image_count integer

Número de imágenes generadas: 1.

input_tokens integer

Tokens de entrada (0 cuando prompt_extend=false).

output_tokens integer

Tokens de salida (0 cuando prompt_extend=false).

output_tokens_detailsobject

Detalles de tokens de salida (solo cuando prompt_extend=true).

Propiedades

reasoning_tokensinteger

Tokens utilizados para el razonamiento.

total_tokensinteger

Tokens totales (0 cuando prompt_extend=false).

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.

Ejecución de 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": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1024,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1024
    },
    "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

Ejecución anómala de la tarea

En caso de error, el sistema devuelve los detalles del error en los campos code y message. Consulte Códigos de error para la solución de problemas.

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

Límites

Las URL de las imágenes son válidas durante 24 horas. Descárguelas pronto.
Moderación de contenido: Tanto el prompt de entrada como la imagen de salida pasan por moderación de contenido. El contenido no conforme devuelve un error IPInfringementSuspect o DataInspectionFailed. Consulte Códigos de error.

Facturación y limitación de tasa

Para precios y cuota gratuita, consulte Precios de modelos.
Para límites de tasa, consulte Z-Image.
La facturación se basa en el recuento de imágenes generadas correctamente y en el estado de prompt_extend. Las llamadas fallidas no generan cargos ni consumen la cuota gratuita.

Códigos de error

Consulte los Códigos de error para solucionar llamadas fallidas.

FAQ

P: ¿Cómo puedo ver las métricas de invocación del modelo?

R: Una hora después de que finalice la invocación de un modelo, vaya a la página de Monitoreo (Singapore) o Monitoreo (China (Pekín)) para ver métricas como el recuento de invocaciones y la tasa de éxito. Para obtener más información, consulte Facturación y gestión de costos.

P: ¿Cómo obtengo la lista blanca de nombres de dominio para el almacenamiento de imágenes?

R: Las imágenes generadas por los modelos se almacenan en OSS. La API devuelve una URL pública temporal. Para configurar una lista blanca de firewall para esta URL de descarga, tenga en cuenta lo siguiente: El almacenamiento subyacente puede cambiar dinámicamente. Este tema no proporciona una lista blanca fija de dominios de OSS para evitar problemas de acceso causados por información obsoleta. Si tiene requisitos de control de seguridad, póngase en contacto con su gestor de cuenta para obtener la lista más reciente de nombres de dominio de OSS.