Alibaba

Qwen Image 2.1

qwen-image-2.1-pro

Modelo de imagem que unifica texto para imagem e edição de imagem, com suporte nativo a resolução 2K e saída RGBA com canal alpha real, permitindo especificar várias regiões de edição com círculos, anotações à mão livre ou máscaras

qwen-image-2.1-pro qwen-image-2.1-turbo

Preços

qwen-image-2.1-pro per image

Preço unitário	$0.050

Visão geral

Qwen Image 2.1 Pro é o nível de alta qualidade da série de modelos de imagem da equipe Qwen da Alibaba, acessível por meio da interface unificada do HiAPI.ai, e o mesmo modelo oferece suporte tanto à geração de imagem a partir de texto quanto à edição de imagem. Ele pode realizar edições como troca de cor, substituição e repintura local com base em 1 a 10 imagens de referência, ou gerar imagens puramente a partir de texto; a saída oferece várias proporções, de 1:1 a 9:16, e é possível fixar o resultado com uma seed e controlar o fundo transparente por meio do prompt. É indicado para fluxos de produto e design que exigem imagens de alta precisão e edição com múltiplas referências.

Destaques principais

Geração e edição no mesmo modelo — não é necessário alternar pesos de modelo entre texto-para-imagem e imagem-para-imagem; uma única cadeia de chamada cobre os dois tipos de tarefa.
Até 10 imagens de referência citadas em ordem — entradas com várias imagens são numeradas conforme a ordem do array e podem ser referenciadas com precisão no prompt como "imagem 1", "imagem 2", facilitando a composição de vários materiais e a edição consistente.
Seed reproduzível para validação de regressão — uma seed aleatória fixa entre 0 e 2147483647 torna o resultado relativamente estável, adequado a fluxos em lote e depuração que exigem geração repetida.
Expansão automática de prompt com opção de ativar/desativar — prompt_extend vem ativado por padrão e melhora bastante prompts curtos; quando for necessário seguir estritamente a formatação do texto original, pode ser desativado para preservar o significado original.

Descrição das capacidades

Texto-para-imagem e edição de imagem unificados: o mesmo modelo pode tanto gerar uma cena a partir do prompt quanto modificar imagens de referência conforme o prompt, reduzindo a fragmentação de estilo e de fluxo causada pelo encadeamento de vários modelos.

Entrada com múltiplas imagens de referência: aceita de 1 a 10 imagens públicas, numeradas na ordem do array e referenciadas no prompt, podendo ser usadas para fusão de vários materiais e edição por regiões.

Saída em várias proporções: cinco proporções disponíveis — 1:1, 16:9, 9:16, 4:3 e 3:4 — correspondendo a tamanhos de até 2688×1536; se não for informada, o modelo escolhe automaticamente com base no prompt e nas imagens de referência.

Controle de fundo transparente: basta indicar "fundo transparente" no prompt para gerar uma imagem com fundo transparente, dispensando a etapa posterior de recorte.

Resultado reproduzível: ao fixar a seed aleatória pelo parâmetro seed, é possível obter saídas relativamente estáveis com as mesmas entradas, facilitando a geração em lote e a regressão de resultados.

Cenários de aplicação

Edição de materiais para equipes de e-commerce e design — envie imagens de referência de produtos ou modelos e use o prompt para especificar troca de cor, substituição de áreas de vestuário e outras modificações, obtendo imagens prontas para páginas de detalhes e materiais publicitários.
Visuais de marca com composição de vários materiais — insira várias imagens de referência e referencie-as em ordem para gerar uma composição visual com estilo unificado, para pôsteres, imagens de redes sociais e materiais de campanha.
Ícones e imagens de produto com fundo transparente — solicite fundo transparente no prompt para produzir diretamente ativos de imagem que podem ser sobrepostos em interfaces ou camadas de composição, reduzindo etapas de pós-processamento.
Pipeline automatizado de geração em lote — fixe a seed e os parâmetros de proporção e integre chamadas de geração ou edição ao pipeline de produção de conteúdo para obter saídas estáveis de séries de imagens.

Limitações e recomendações de escolha

Este modelo é o nível de alta qualidade da série, com tempo de geração e custo por imagem superiores aos do nível turbo da mesma série, sendo indicado para cenários que exigem alta qualidade de imagem; para pré-visualizações em grande volume ou triagem inicial de baixo custo, pode-se considerar o nível turbo. As imagens de referência de entrada devem ser URLs acessíveis publicamente, com no máximo 10 MB por imagem e proporção entre o lado maior e o menor de no máximo 10:1. O limite do prompt é de 4500 caracteres; quando for necessário seguir estritamente a formatação do texto original, recomenda-se desativar a expansão automática. Se a tarefa priorizar latência extremamente baixa ou exigir apenas geração simples em lote, deve-se avaliar uma opção mais leve.

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: qwen-image-2.1-pro

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

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

seedintegerOpcionalmin 0max 2147483647

Semente aleatória, número inteiro de 0 a 2147483647; fixar esse valor torna o resultado da geração relativamente estável; se não for informado, será gerado aleatoriamente.

promptstringObrigatóriominLength 1maxLength 4500

Descreva o conteúdo da imagem a ser gerada, ou indique quais modificações devem ser feitas na imagem de referência; pode ser em chinês ou inglês, os textos que precisam ser renderizados devem ser escritos literalmente no prompt, e quando for necessário fundo transparente, escreva "fundo transparente" no prompt.

image_urlsarrayOpcionalminItems 1maxItems 10

Array de URLs públicas de imagens de referência ou de imagens a serem editadas, de 1 a 10 imagens; se não for informado, será geração de imagem a partir de texto; várias imagens são numeradas na ordem do array (podendo ser referidas como "imagem 1", "imagem 2"). Suporta JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF, com no máximo 10 MB por imagem, largura e altura entre 1 e 8000 pixels (recomenda-se 384–2048), e proporção entre o lado maior e o lado menor não superior a 10:1.

Array [ string ]

aspect_ratiostringOpcional

Proporção da imagem de saída, com valor em string, correspondendo a tamanhos como 2048×2048, 2688×1536, 1536×2688, 2368×1728, 1728×2368; se não for informado, o modelo escolherá automaticamente com base no prompt e na imagem de referência.

Opções:1:116:99:164:33:4

prompt_extendbooleanOpcionalPadrão: true

Define se o prompt deve ser otimizado automaticamente, valor booleano, padrão true; quando ativado, melhora significativamente prompts curtos, mas acrescenta alguns segundos de tempo de processamento; pode ser desativado quando for necessário seguir estritamente o layout do texto original.

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": "qwen-image-2.1-pro",
  "input": {
    "prompt": "…",
    "prompt_extend": true
  }
}'

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: "qwen-image-2.1-pro",
    input: {
      "prompt": "…",
      "prompt_extend": true
    }
  }),
});
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": "qwen-image-2.1-pro",
        "input": {
          "prompt": "…",
          "prompt_extend": True
        }
    },
)
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"
    }
  }
}