Skip to main content
Z-Image

Z-Image API reference

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.

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.

Consulte 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.
O 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)
Ativar 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
  • Execução anormal 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"
    }
output objectSaída do modelo.

Propriedades

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

Propriedades

finish_reason stringMotivo da conclusão. O valor stop indica sucesso.message objectMensagem de resposta do modelo.

Propriedades

rolestringFunção da mensagem. O valor é assistant.contentarray

Propriedades

image stringURL da imagem gerada (PNG). Válida por 24 horas. Baixe-a imediatamente.text stringRetorna o prompt de entrada (prompt_extend=false) ou o prompt reescrito (prompt_extend=true).
reasoning_content stringProcesso de raciocínio do modelo. Retornado apenas quando prompt_extend=true.
usage objectInclui estatísticas de uso apenas para gerações bem-sucedidas.

Propriedades

width integerLargura da imagem gerada (pixels).height integerAltura da imagem gerada (pixels).image_count integerNúmero de imagens geradas: 1.input_tokens integerTokens de entrada (0 quando prompt_extend=false).output_tokens integerTokens de saída (0 quando prompt_extend=false).output_tokens_detailsobjectDetalhes dos tokens de saída (apenas quando prompt_extend=true).

Propriedades

reasoning_tokensintegerTokens usados para raciocínio.
total_tokensintegerTotal de tokens (0 quando prompt_extend=false).
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.
message stringMensagem 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.
Referência da API de Geração de Texto
Geração de Imagens
Geração de Vídeo
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos