Text-to-image Z-Image API reference - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Modelo leve de texto para imagem com geração rápida, renderização de texto em chinês e inglês e resoluções flexíveis.

Teste online: (Singapore | Beijing) | Blog técnico

Exemplos

Prompt de entrada	Imagem de saída
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.

Prompt de entrada

Imagem de saída

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.

b16c8008-83c1-4c80-ae22-786a2299bec3-1-转换自-png

Visão geral do modelo

Nome do modelo	Descrição	Especificações da imagem de saída
z-image-turbo	Modelo leve e rápido para geração de imagens	Resolução da imagem: de 512×512 a 2048×2048 pixels. Consulte as resoluções recomendadas nas configurações do parâmetro size. Formato da imagem: png Quantidade de imagens: fixa em 1.

Nome do modelo

Descrição

Especificações da imagem de saída

z-image-turbo

Modelo leve e rápido para geração de imagens

Resolução da imagem: de 512×512 a 2048×2048 pixels. Consulte as resoluções recomendadas nas configurações do parâmetro size.

Formato da imagem: png

Quantidade de imagens: fixa em 1.

ObservaçãoConsulte a Lista de modelos para verificar o suporte por região antes de chamar a API.

Pré-requisitos

Crie uma chave de API e defina a chave de API como variável de ambiente.

ImportanteO Alibaba Cloud Model Studio lançou domínios específicos para workspaces nas regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:

China (Beijing): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

Chamada HTTP síncrona

Singapore: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

Substitua {WorkspaceId} pelo seu ID do workspace real.

Parâmetros da solicitação

Texto para imagem

Este exemplo retorna uma imagem diretamente para acelerar a resposta. Para ativar a reescrita inteligente, defina prompt_extend=true. Nesse caso, o sistema retorna o prompt otimizado, o raciocínio e a imagem, o que aumenta o tempo de resposta.

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

Cabeçalhos da solicitação

Content-Type string (Obrigatório)

Tipo de conteúdo da solicitação. Use application/json.

Authorization string (Obrigatório)

Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

Corpo da solicitação

model string (Obrigatório)

Nome do modelo: z-image-turbo.

input object (Obrigatório)

Conteúdo de entrada.

Propriedades

messages array (Obrigatório)

Array de conteúdo da solicitação. Apenas turno único: informe um conjunto de role e content. Não há suporte para múltiplos turnos.

Propriedades

rolestring (Obrigatório)

Função da mensagem: user.

contentarray (Obrigatório)

Array de conteúdo da mensagem. Deve conter um objeto de texto.

Propriedades

textstring(Obrigatório)

Prompt positivo que descreve o conteúdo, o estilo e a composição desejados.

Suporta chinês e inglês. Limite de 800 caracteres (cada caractere, letra, número ou símbolo conta como um). O sistema trunca caracteres excedentes.

Exemplo: Um gato laranja sentado com expressão feliz, animado e fofo, realista e preciso.

Nota: Há suporte para apenas um objeto de texto. Informar zero ou múltiplos objetos de texto resulta em erro.

parameters object (Opcional)

Parâmetros de geração de imagem.

Propriedades

size string (Opcional)

Resolução da imagem de saída no formato largura×altura.

Padrão: 1024*1536
Intervalo: de 512×512 a 2048×2048
Recomendado: de 1024×1024 a 1536×1536

Exemplo: 1024*1536.

Resoluções recomendadas para um total de 1024*1024 pixels:

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

Resoluções recomendadas para um total de 1280*1280 pixels:

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

Resoluções recomendadas para um total de 1536*1536 pixels:

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)

ImportanteAtivar prompt_extend aumenta o custo. Consulte Preços do modelo para obter detalhes.

Ativa a reescrita inteligente de prompts via otimização LLM e saída de raciocínio.

false (padrão): Retorna a imagem e o prompt original
true: Retorna a imagem, o prompt otimizado e o raciocínio

seed integer (opcional)

Semente de número aleatório. Intervalo válido: [0,2147483647].

Usar o mesmo seed gera saídas semelhantes. Se omitido, o algoritmo usa uma semente aleatória.

Nota: A geração de imagens é probabilística. Mesmo com o mesmo seed, os resultados podem variar.

Parâmetros da resposta

Execução bem-sucedida da tarefa

Os dados da tarefa (status e URLs das imagens) ficam retidos por apenas 24 horas e depois são removidos automaticamente. Salve as imagens geradas imediatamente.

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

Execução anormal da tarefa

Em caso de falha, o sistema retorna detalhes do erro nos campos code e message. Consulte Códigos de erro para solucionar problemas.

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

output object

Saída do modelo.

Propriedades

choices array

Conteúdo de saída do modelo. O array contém um elemento.

Propriedades

finish_reason string

Motivo da conclusão. O valor stop indica sucesso.

message object

Mensagem de resposta do modelo.

Propriedades

rolestring

Função da mensagem. O valor é assistant.

contentarray

Propriedades

image string

URL da imagem gerada (PNG). Válida por 24 horas. Baixe-a imediatamente.

text string

Retorna o prompt de entrada (prompt_extend=false) ou o prompt reescrito (prompt_extend=true).

reasoning_content string

Processo de raciocínio do modelo. Retornado apenas quando prompt_extend=true.

usage object

Inclui estatísticas de uso apenas para gerações bem-sucedidas.

Propriedades

width integer

Largura da imagem gerada (pixels).

height integer

Altura da imagem gerada (pixels).

image_count integer

Número de imagens geradas: 1.

input_tokens integer

Tokens de entrada (0 quando prompt_extend=false).

output_tokens integer

Tokens de saída (0 quando prompt_extend=false).

output_tokens_detailsobject

Detalhes dos tokens de saída (apenas quando prompt_extend=true).

Propriedades

reasoning_tokensinteger

Tokens usados para raciocínio.

total_tokensinteger

Total de tokens (0 quando prompt_extend=false).

request_id string

Identificador exclusivo da solicitação para rastreamento e solução de problemas.

code string

Código de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.

message string

Mensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.

Limites

As URLs das imagens são válidas por 24 horas. Baixe-as imediatamente.
Moderação de conteúdo: Tanto o prompt de entrada quanto a imagem de saída passam por moderação de conteúdo. Conteúdo não compatível retorna um erro IPInfringementSuspect ou DataInspectionFailed. Consulte Códigos de erro.

Faturamento e limitação de taxa

Para preços e cota gratuita, consulte Preços do modelo.
Para limites de taxa, consulte Z-Image.
O faturamento baseia-se na quantidade de imagens geradas com sucesso e no status de prompt_extend. Chamadas com falha não geram cobranças nem consomem a cota gratuita.

Códigos de erro

Consulte Códigos de erro para solucionar problemas em chamadas com falha.

Perguntas frequentes

P: Como visualizo as métricas de invocação do modelo?

R: Uma hora após a conclusão da invocação do modelo, acesse a página Monitoring (Singapore) ou Monitoring (China (Beijing)) para visualizar métricas como contagem de invocações e taxa de sucesso. Para mais informações, consulte Faturamento e gestão de custos.

P: Como obtenho a lista de permissões de nomes de domínio para armazenamento de imagens?

R: As imagens geradas pelos modelos são armazenadas no OSS. A API retorna uma URL pública temporária. Para configurar uma lista de permissões de firewall para esta URL de download, observe o seguinte: o armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de permissões de nomes de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se você tiver requisitos de controle de segurança, entre em contato com seu gerente de conta para obter a lista mais recente de nomes de domínio do OSS.