Alibaba

Z-Image

z-image

Modelo de texto para imagem de código aberto do Tongyi da Alibaba, com arquitetura DiT de fluxo único e cerca de 6 bilhões de parâmetros, destacando-se na renderização de texto em chinês e inglês e na aderência a instruções bilíngues

z-image

Experimentar z-image

Entrada

Criações

Ver todas as criações

Saída

Preencha os parâmetros e gere — os resultados aparecerão aqui.

Preços

z-image per image

Preço unitário	$0.008

Apresentação

z-image é um modelo de texto para imagem lançado pelo Laboratório Tongyi da Alibaba, acessível por meio da interface unificada do HiAPI.ai, capaz de gerar imagens realistas ou artísticas a partir de prompts em chinês e inglês, com suporte à composição tipográfica de caracteres chineses e ingleses dentro da imagem. Indicado para desenvolvedores que precisam produzir rapidamente visuais criativos, pôsteres e ilustrações estilizadas, e também para cenários de avaliação de integração que acompanham as capacidades de modelos de código aberto.

Destaques principais

Prompts bilíngues em chinês e inglês com renderização de texto na imagem — os prompts aceitam entrada em chinês e inglês, e o modelo consegue renderizar textos nesses idiomas na imagem gerada, facilitando a criação de materiais visuais com textos.
Arquitetura DiT de fluxo único, com alta eficiência de parâmetros — modela de forma unificada as condições de texto e de imagem no nível da sequência, alcançando qualidade visual utilizável com um volume de parâmetros menor.
Várias proporções de quadro selecionáveis de uma vez — a saída suporta cinco proporções: 1:1, 4:3, 3:4, 16:9 e 9:16, cobrindo necessidades de formato quadrado, horizontal e vertical.
Geração de imagens leve com cobrança por imagem — a interface cobra pelo número de imagens geradas, tendo o prompt e a proporção como únicos itens de entrada, o que simplifica a integração e o cálculo de custos.

Descrição das capacidades

Texto para imagem em chinês e inglês: basta inserir um prompt em chinês ou inglês com até 1000 caracteres para gerar uma imagem, adequado para validar rapidamente direções criativas ou produzir materiais ilustrativos em lote.

Renderização de texto na imagem: é possível apresentar textos em chinês e inglês na imagem, adequado para criar esboços visuais com títulos ou slogans, reduzindo a necessidade de diagramação posterior.

Controle de proporção: especifique uma das cinco proporções por meio de aspect_ratio, com padrão 1:1, correspondendo diretamente às exigências de composição de diferentes posicionamentos de anúncio.

Desempenho realista e estilizado: a mesma interface atende tanto a saídas de cenas realistas quanto a resultados artísticos estilizados, cobrindo desde visuais de produto até ilustrações criativas.

Cenários de aplicação

Profissionais de marketing criando imagens para redes sociais — gerar imagens verticais ou quadradas com prompts em chinês e inglês e proporção definida, para uso direto na publicação de conteúdo em plataformas sociais.
Designers gerando imagens de base e títulos para pôsteres — inserir um prompt contendo o texto do título para obter uma imagem com diagramação tipográfica, usada como rascunho de pôster antes do refinamento.
Desenvolvedores integrando capacidade de texto para imagem — enviar prompt e proporção pela interface unificada e conectar as imagens geradas ao próprio aplicativo ou fluxo de produção de conteúdo.
Equipes criativas explorando estilos — alternar descrições de estilo com o mesmo prompt para gerar imagens rapidamente, auxiliando na comparação de propostas e na definição da direção visual.

Limitações e recomendações de escolha

No momento, a interface aceita apenas dois itens de entrada: prompt de texto e proporção, não sendo possível fazer edição de imagem ou referência com múltiplas imagens por meio de entrada de imagem, nem oferecendo parâmetros detalhados como número de passos ou intensidade de estilo. Para tarefas que exigem controle preciso de composição, edição em camadas ou reprodução consistente de personagens, deve-se optar por modelos que ofereçam essas capacidades. O resultado gerado é bastante influenciado pela forma como o prompt é escrito; recomenda-se validar o efeito com poucas imagens antes de fazer chamadas em lote.

Perguntas frequentes

Ver todas as perguntas →

Para que serve o Z-Image?

É adequado para geração de imagens de baixo custo com prompts em chinês, retratos realistas, letreiros, cenas noturnas urbanas e materiais gastronômicos.
Quais proporções de imagem são suportadas?

Suporta 1:1, 4:3, 3:4, 16:9 e 9:16.
É possível controlar a resolução ou o formato?

O contrato de requisição público atual expõe apenas Prompt e aspect_ratio; campos de resolução ou formato não declarados não devem ser adicionados à requisição.
Suporta imagens de referência?

Não. O ID atual do modelo Z-Image é apenas texto para imagem.

Criar uma tarefa de geração

POST https://api.hiapi.ai/v1/tasks

Cabeçalhos

AuthorizationstringObrigatório

Chave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API

Content-TypestringOpcional

O corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.

Idempotency-KeystringOpcional

Chave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.

Chave de idempotência

Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.

Corpo

modelstringObrigatório

Valor fixo atual: z-image

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

Objeto de parâmetros de negócio para z-image e a rota default — veja a tabela de parâmetros abaixo.

promptstringObrigatóriomaxLength 1000

Prompt de texto para geração de imagem, que controla o conteúdo da imagem de saída; aceita chinês e inglês.

aspect_ratiostringOpcionalPadrão: "1:1"

Proporção largura-altura da imagem de saída; o padrão é 1:1.

Opções:1:14:33:416:99:16

callbackobjectOpcional

Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.

Callbacks (Webhook)

Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.

urlstringObrigatório

Obrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.

whenstringOpcionalPadrão: "final"

Atualmente só há suporte a final — notifica tanto em success quanto em fail.

Opções:final

storagestringOpcionalPadrão: "temp"

Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.

Opções:temppersistent

Exemplos de requisição

# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geração)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "z-image",
  "input": {
    "prompt": "…",
    "aspect_ratio": "1:1"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "z-image",
    input: {
      "prompt": "…",
      "aspect_ratio": "1:1"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "z-image",
        "input": {
          "prompt": "…",
          "aspect_ratio": "1:1"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obter detalhes da tarefa

GET https://api.hiapi.ai/v1/tasks/:id

Campos da resposta

taskIdstringObrigatório

ID da tarefa, sempre com prefixo tk-hiapi-.

modelstringObrigatório

Nome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.

routestringOpcional

Presente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.

statusstringObrigatório

Estado da tarefa.

Valores de status

queued Na fila, ainda não iniciada. handling Em processamento. archiving Processamento concluído, preparando artefatos. success Terminal: concluído, artefatos disponíveis (retorna output). fail Terminal: falha (retorna error). Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.

creatednumberObrigatório

Momento de criação da tarefa (segundos Unix).

completednumberObrigatório

Segundos Unix do estado terminal; 0 enquanto não terminal.

outputarrayOpcional

Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).

Array [ object ]

Itens do array

urlstringObrigatório

URL do artefato, baixável diretamente.

typestringObrigatório

Valores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.

expireAtnumberObrigatório

Segundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.

errorobjectOpcional

Presente apenas com status == fail.

codestringObrigatório

Código de erro de negócio.

messagestringObrigatório

Descrição do erro.

Exemplos de resposta

Sucesso

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Em processamento (não final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Falhou

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}