Início Rápido: Qwen Image Text-to-Image para Gerar Imagens a partir de Prompts

A API Qwen Image text-to-image na Novita AI gera imagens a partir de prompts de texto usando o modelo Qwen Image de 20B — a mesma base que alimenta a API Qwen Image Edit para tarefas de edição precisas. Este início rápido cobre o fluxo de trabalho assíncrono completo: envie uma solicitação de geração, obtenha um ID de tarefa, faça polling até a conclusão e recupere a URL da sua imagem. O endpoint é POST https://api.novita.ai/v3/async/qwen-image-txt2img.

Quando Usar Este Início Rápido

Use este guia quando precisar:

• Gerar imagens a partir de prompts de texto com renderização de texto de alta qualidade em inglês ou chinês via POST /v3/async/qwen-image-txt2img.
• Construir pipelines que criem cartazes, elementos gráficos ou conteúdo ilustrado onde a legibilidade do texto dentro da imagem seja importante.
• Prototipar rapidamente contra uma API hospedada, em vez de executar o modelo de 20B em infraestrutura GPU local.

O modelo Qwen Image é especialmente forte em gerar imagens com texto legível e estilizado embutido na saída — pense em cartazes, placas, maquetes de produtos e capas gráficas. Se o seu caso de uso envolve editar uma imagem existente em vez de gerar do zero, veja a API Qwen Image Edit. Se você quiser uma visão geral completa dos recursos e benchmarks do modelo Qwen Image, o post de lançamento do Qwen Image na Novita AI cobre a arquitetura e os resultados de benchmark em detalhes.

Passo 1: Obtenha sua Chave de API Novita

Crie uma conta Novita AI e navegue até gerenciamento de chaves de API. Gere uma chave e armazene-a como uma variável de ambiente:

export NOVITA_API_KEY="sua_chave_api_aqui"

Mantenha a chave fora do código do lado do cliente, bundles frontend e controle de versão.

Passo 2: Confirme o Endpoint e o Modelo

Item	Valor
Endpoint de geração	POST https://api.novita.ai/v3/async/qwen-image-txt2img
Endpoint de polling de resultado	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Modelo	Qwen Image (20B MMDiT)
Documentação da API	Referência Qwen Image txt2img da Novita AI

A API segue um padrão assíncrono de duas etapas comum a todos os endpoints de geração de imagem da Novita AI. A chamada de geração retorna apenas um task_id; você consulta o endpoint de resultado separadamente até que a tarefa seja concluída.

O preço é de $0,02 por imagem, consistente com o endpoint Qwen Image Edit. Verifique a taxa atual na página de preços da Novita AI antes de fazer uma estimativa de custo.

Passo 3: Envie sua Primeira Requisição

Envie um POST para o endpoint de geração com um prompt e um size opcional:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Uma paisagem montanhosa cinematográfica ao nascer do sol, luz dourada quente, ultra-detalhada, 8K",
    "size": "1024*1024"
  }'

Uma resposta 200 bem-sucedida retorna:

{
  "task_id": "abc123..."
}

Salve o task_id. Você o usará no próximo passo.

Passo 4: Faça Polling para Obter o Resultado

Envie um GET para o endpoint de resultado da tarefa com o task_id como parâmetro de consulta:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

A resposta inclui um campo status. Continue fazendo polling até que o status seja TASK_STATUS_SUCCEED:

{
  "task": {
    "task_id": "abc123...",
    "status": "TASK_STATUS_SUCCEED"
  },
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "3600",
      "image_type": "png"
    }
  ]
}

A image_url é uma URL com tempo limitado — o valor image_url_ttl (em segundos) informa por quanto tempo ela permanece válida. Baixe a imagem imediatamente ou a sirva através de seu próprio armazenamento se precisar de acesso de longo prazo.

Valores de status a serem tratados:

Status	Significado
TASK_STATUS_QUEUED	Requisição está na fila, ainda não iniciada
TASK_STATUS_PROCESSING	Geração em andamento
TASK_STATUS_SUCCEED	Imagem está pronta; leia images[0].image_url
TASK_STATUS_FAILED	Geração falhou; verifique task.reason

Exemplo em Python: Ponta a Ponta

Este script envia uma requisição de geração, faz polling até a conclusão e imprime a URL da imagem.

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"


def generate_image(prompt: str, size: str = "1024*1024") -> str:
    response = requests.post(
        f"{BASE_URL}/v3/async/qwen-image-txt2img",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"prompt": prompt, "size": size},
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, max_attempts: int = 60) -> str:
    for _ in range(max_attempts):
        response = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        elif status == "TASK_STATUS_FAILED":
            reason = data["task"].get("reason", "unknown")
            raise RuntimeError(f"Geração falhou: {reason}")

        time.sleep(interval)

    raise TimeoutError(f"Tarefa {task_id} não foi concluída após {max_attempts} polls")


if __name__ == "__main__":
    prompt = (
        "Um cartaz com os dizeres 'Bem-vindo à Novita AI' em letras neon em negrito "
        "contra um horizonte urbano escuro à noite, iluminação cinematográfica"
    )
    task_id = generate_image(prompt, size="1024*1024")
    print(f"ID da Tarefa: {task_id}")

    image_url = poll_result(task_id)
    print(f"URL da Imagem: {image_url}")

Exemplo cURL

Padrão de dois comandos para o fluxo de trabalho completo:

# Passo 1: Enviar requisição de geração
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Um jardim japonês sereno com cerejeiras, lago de carpas, névoa matinal, estilo aquarela",
    "size": "1024*1536"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")

echo "ID da Tarefa: $TASK_ID"

# Passo 2: Fazer polling até concluir
while true; do
  STATUS=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['task']['status'])")
  echo "Status: $STATE"
  if [ "$STATE" = "TASK_STATUS_SUCCEED" ]; then
    echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['images'][0]['image_url'])"
    break
  elif [ "$STATE" = "TASK_STATUS_FAILED" ]; then
    echo "Geração falhou"
    break
  fi
  sleep 2
done

Parâmetros Principais

Parâmetro	Tipo	Obrigatório	Padrão	Observações
prompt	string	Sim	—	Descrição textual da imagem a ser gerada. Suporta inglês e chinês.
size	string	Não	1024*1024	Largura × altura em pixels, formatado como L*A. Cada dimensão: 256–1536.

Opções de tamanho a considerar:

Caso de uso	Tamanho recomendado
Quadrado (redes sociais, perfil)	1024*1024
Retrato (mobile, cartaz)	1024*1536
Paisagem (banner, miniatura)	1536*1024

Não há parâmetros separados de negative_prompt, steps ou cfg_scale neste endpoint — o modelo lida com essas decisões internamente. Concentre seu prompt no que a imagem deve conter e em seu estilo visual.

O que o Qwen Image Gera Bem

A arquitetura MMDiT de 20B dá ao Qwen Image uma vantagem genuína em algumas áreas específicas:

Texto em imagens. A maioria dos modelos de geração de imagem tem dificuldade com texto legível — palavras ficam borradas, letras trocam e layouts de várias linhas colapsam. O Qwen Image lida com texto em inglês e chinês com precisão notavelmente melhor. Cartazes, placas, rótulos e gráficos legendados são casos de uso viáveis, não um lance de cara ou coroa.

Consistência semântica. Quando um prompt descreve uma cena com múltiplos elementos e relações espaciais específicas, o Qwen Image tende a honrar a intenção do layout de forma mais confiável do que arquiteturas menores ou mais antigas.

Seguimento de prompts em escala. Prompts longos e detalhados que descrevem múltiplos atributos — cena, iluminação, estilo, paleta de cores, objetos específicos — produzem saídas que refletem o prompt completo em vez de se ater a uma única palavra-chave.

Onde é menos adequado: fluxos de trabalho de geração em tempo real ou interativos. O padrão assíncrono implica latência inerente entre requisição e resultado. Se seu caso de uso requer feedback de sub-segundo, este endpoint não é a escolha certa.

Erros Comuns e Correções

401 Não Autorizado: Verifique se o cabeçalho Authorization está formatado como Bearer <chave> com um espaço após Bearer. Confirme se a chave está ativa no console Novita AI.

400 Requisição Inválida no size: O parâmetro size deve usar * como separador (ex.: 1024*1024), não x, × ou um array JSON. Cada dimensão deve estar entre 256 e 1536.

TASK_STATUS_FAILED sem motivo: Geralmente causado por um prompt que aciona a filtragem de conteúdo. Simplifique o prompt e tente novamente. Evite prompts com violência explícita, conteúdo sexual ou conteúdo que possa ativar filtros de segurança.

URL da imagem expirada (403 ou 404 na URL): O campo image_url_ttl informa por quanto tempo a URL é válida. Baixe a imagem imediatamente após o polling ser bem-sucedido, ou armazene-a em seu próprio armazenamento de objetos.

Polling lento: O tempo de geração varia com a carga do servidor. Começar o polling em intervalos de 2 segundos é razoável. Se a tarefa ainda estiver como TASK_STATUS_QUEUED após 10 segundos, continue fazendo polling — a profundidade da fila pode aumentar durante horários de pico.

Perguntas Frequentes

Existe um endpoint compatível com OpenAI para o Qwen Image txt2img?

Não. O endpoint /v3/async/qwen-image-txt2img usa a API de imagem assíncrona nativa da Novita AI, não o formato de geração de imagem do OpenAI. Se você precisar de geração de imagem compatível com OpenAI, a Novita AI oferece modelos FLUX e SDXL através de endpoints compatíveis — veja a documentação da Novita AI.

Qual é a diferença entre este endpoint e o endpoint Qwen Image Edit?

Este endpoint gera imagens apenas a partir de um prompt de texto — nenhuma imagem de entrada é necessária. O endpoint Qwen Image Edit recebe uma imagem existente mais uma instrução de texto e modifica a imagem de acordo. Use txt2img quando estiver criando do zero; use edit quando precisar alterar algo em uma imagem existente.

O modelo suporta proporções diferentes de quadrado?

Sim. Use o parâmetro size para definir largura e altura independentemente, entre 256 e 1536 pixels por dimensão. Proporções altas (ex.: 1024*1536) funcionam bem para conteúdo retrato; proporções largas (ex.: 1536*1024) são adequadas para banners e miniaturas.

Como obtenho resultados consistentes em múltiplas gerações?

Não há parâmetro seed no endpoint txt2img. Cada requisição produz um resultado diferente. Se você precisar de saída reproduzível, salve a URL da imagem imediatamente e armazene a imagem em seu próprio armazenamento, em vez de regenerar.

Posso usar esta API em um job em lote?

Sim. Envie múltiplas requisições de geração e colete os IDs das tarefas, depois faça polling delas em paralelo. Cada requisição retorna seu próprio task_id, então fluxos de trabalho em lote são diretos — você não precisa esperar uma terminar para enviar a próxima.

Artigos Recomendados

• Qwen-Image na Novita AI: Renderização de Texto Superior com o Modelo de 20B
• Qwen-Image-Edit na Novita AI: Edição de Nível Profissional por Apenas $0,02
• FLUX.1 Kontext Pro vs Max vs Dev na Novita AI