API Qwen Image 3.0: preços e integração

O Qwen Image 3.0 combina geração de texto para imagem e edição com imagens de referência em uma única API assíncrona. Pela APIMart, você envia uma tarefa, consulta o status e recupera uma ou mais imagens quando o processamento termina.

Este guia cobre o que importa antes da integração: preços atuais de Standard e Pro, autenticação, parâmetros, leitura de respostas, polling, novas tentativas e armazenamento. Para recursos e benchmarks, consulte o guia de lançamento do Qwen Image 3.0.

Preços e acesso ao Qwen Image 3.0

A APIMart oferece dois IDs de modelo:

• qwen-image-3.0 para Standard
• qwen-image-3.0-pro para Pro

A cobrança é feita por imagem gerada, não por Token de entrada. A tabela reflete a página de preços da APIMart em 27 de agosto de 2026; os valores podem mudar.

Comparação de preços entre Standard e Pro

Standard tem atualmente o mesmo preço em 1K e 2K. Pro 2K custa o dobro de Pro 1K. Segundo a documentação do Qwen Image 3.0, gerações que falham são reembolsadas e imagens de referência não acrescentam uma cobrança de geração separada.

Estimando uma carga real

A fórmula básica é:

custo mensal = imagens concluídas × preço por imagem

n controla a quantidade de saídas, portanto uma solicitação com n: 4 pode cobrar quatro imagens. Inclua testes de prompt, variações e novas gerações no orçamento.

Standard atende à maioria dos rascunhos e materiais comuns. Avalie Pro quando ganhos em texto, composição ou detalhes justificarem o custo. Com Pro, use 1K nas iterações e reserve 2K para resultados finais aprovados em alta resolução.

Acesso e autenticação

Crie uma conta APIMart, adicione saldo suficiente e gere uma chave no console. Guarde-a em um Secret ou variável de ambiente no servidor; nunca a exponha no navegador nem em uma variável NEXT_PUBLIC_*.

Base URL e Bearer Token

Os exemplos usam esta Base URL:

https://api.apimart.ai/v1

Envie a chave como Bearer Token:

Authorization: Bearer <your_api_key>
Content-Type: application/json

Uma chave ausente ou inválida normalmente retorna 401, saldo insuficiente pode retornar 402 e limite de requisições, 429. Registre a resposta e o contexto no servidor, mas oculte a chave antes de salvar os logs.

Geração, edição e fluxo assíncrono

Geração e edição usam POST /v1/images/generations. A API retorna primeiro um ID de tarefa em vez de esperar pela imagem pronta.

Parâmetros principais

Em dimensões personalizadas, cada lado deve ter entre 512 e 2.048 pixels e a proporção deve ficar entre 1:8 e 8:1. As referências aceitam JPEG, PNG, BMP, TIFF, WebP e GIF, com limite documentado de 10 MB por imagem. Confira a referência de geração antes do lançamento, pois os limites podem evoluir.

O anúncio oficial do Qwen Image 3.0 descreve renderização de texto nativa em 12 idiomas. Coloque entre aspas o texto que precisa aparecer exatamente e valide ortografia, tipografia e layout na resolução final.

Exemplo de texto para imagem

{
  "model": "qwen-image-3.0",
  "prompt": "Um banner de produto limpo com o texto exato \"Promoção de verão\", tipografia geométrica em negrito e fundo laranja quente",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

Exemplo de edição com referência

Adicione image_urls para transformar uma imagem existente:

{
  "model": "qwen-image-3.0-pro",
  "prompt": "Manter o formato do produto inalterado e trocar o fundo por um estúdio com iluminação suave",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

A URL de referência deve estar acessível para a API. Para arquivos privados, use uma URL assinada válida durante o envio e processamento ou, quando adequado, uma Data URL compatível.

Fluxo assíncrono de tarefas

O fluxo tem três etapas:

1. Envie uma tarefa com POST /v1/images/generations.
2. Leia data[0].task_id na resposta.
3. Consulte GET /v1/tasks/{task_id} até concluir ou falhar.

Resposta do envio

Uma resposta bem-sucedida tem este formato:

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

Não leia task_id no objeto superior: ele está no primeiro item de data.

Polling e resultado concluído

Consulte a cada três a cinco segundos, em vez de enviar requisições de status continuamente. Os arquivos prontos ficam em data.result.images:

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example-cdn.com/generated-image.png"
          ]
        }
      ]
    }
  }
}

A documentação atual informa que a APIMart replica as imagens concluídas no CDN da plataforma e as mantém disponíveis no longo prazo. Mesmo assim, copie os materiais aprovados para seu armazenamento quando precisar controlar retenção, exclusão, acesso ou desempenho de entrega.

Exemplos de integração

Integração com Python

Este exemplo no servidor envia uma tarefa, consulta a cada três segundos e encerra a espera após três minutos:

import os
import time
import requests

API_KEY = os.environ["QWEN_API_KEY"]
BASE_URL = "https://api.apimart.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=HEADERS,
        json={"model": "qwen-image-3.0", "prompt": prompt, "resolution": "1K", "n": 1, "prompt_extend": True},
        timeout=30,
    )
    response.raise_for_status()
    task_id = response.json()["data"][0]["task_id"]
    deadline = time.monotonic() + 180

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        task = poll.json()["data"]
        if task["status"] == "completed":
            return task["result"]["images"][0]["url"][0]
        if task["status"] == "failed":
            raise RuntimeError(task.get("fail_reason", "Generation failed"))
        time.sleep(3)

    raise TimeoutError(f"Task {task_id} did not finish within 180 seconds")

Em uma aplicação real, salve o ID antes do polling. Se um Worker reiniciar, outro poderá retomar a tarefa salva sem enviar e pagar por uma geração duplicada.

Integração com JavaScript

Execute este código apenas em um servidor confiável:

const apiKey = process.env.QWEN_API_KEY;
const baseUrl = "https://api.apimart.ai/v1";
const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, headers });
  const payload = await response.json();
  if (!response.ok) throw new Error(`APIMart ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

async function generateImage(prompt) {
  const submission = await requestJson(`${baseUrl}/images/generations`, {
    method: "POST",
    body: JSON.stringify({
      model: "qwen-image-3.0", prompt, resolution: "1K", n: 1, prompt_extend: true,
    }),
  });
  const taskId = submission.data[0].task_id;
  const deadline = Date.now() + 180_000;

  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const { data: task } = await requestJson(`${baseUrl}/tasks/${taskId}`);
    if (task.status === "completed") return task.result.images[0].url[0];
    if (task.status === "failed") throw new Error(task.fail_reason ?? "Generation failed");
  }
  throw new Error(`Task ${taskId} did not finish within 180 seconds`);
}

O mesmo fluxo pode ser testado com cURL:

curl -X POST https://api.apimart.ai/v1/images/generations \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0","prompt":"Uma fotografia minimalista de produto","resolution":"1K","n":1}'

curl https://api.apimart.ai/v1/tasks/<task_id> \
  -H "Authorization: Bearer <your_api_key>"

Checklist para produção

Uma chamada bem-sucedida é apenas o começo. Um pipeline confiável também precisa de novas tentativas limitadas, estado persistente, observabilidade e armazenamento controlado.

Erros e política de novas tentativas

Não reenvie uma geração automaticamente após um timeout ambíguo. Se o servidor aceitou a primeira solicitação, a segunda pode criar tarefa e cobrança duplicadas. Salve cada ID retornado e separe as novas tentativas de envio das novas tentativas de polling.

Antes do lançamento

• Mantenha a chave apenas em um Secret do servidor.
• Valide prompt, resolution, size, n e referências antes do envio.
• Salve o ID e o estado atual da tarefa.
• Consulte a cada três a cinco segundos com timeout na aplicação.
• Use backoff exponencial com jitter para 429 e 5xx recuperáveis.
• Limite a concorrência conforme taxas e latências observadas.
• Monitore separadamente tarefas concluídas, falhas, timeouts e duplicadas.
• Copie resultados aprovados para seu armazenamento quando precisar controlar a retenção.
• Antes da produção, revise a página do modelo Qwen Image 3.0, os preços e a documentação.

Gere imagens com Qwen Image 3.0

Teste Standard e Pro com a API unificada da APIMart, compare resultados em 1K e 2K e leve seu fluxo de imagens do protótipo à produção.

Explorar Qwen Image 3.0

Perguntas frequentes

Por quanto tempo devo fazer polling antes do timeout?

A APIMart recomenda consultas a cada três a cinco segundos e sugere cerca de três minutos de timeout no cliente. Use isso como ponto de partida, meça a latência real e guarde o ID para reconciliar tarefas que excederam o prazo.

As URLs de resultado expiram após 24 horas?

A documentação atual informa que as saídas são replicadas no CDN da plataforma e ficam disponíveis no longo prazo. Portanto, a antiga afirmação de 24 horas não se aplica a esta integração. Salve materiais críticos em sua infraestrutura, sem depender apenas de uma retenção externa sem prazo garantido.

Posso enviar uma referência em Base64?

Sim. A documentação aceita de uma a três URLs públicas HTTP/HTTPS ou Data URLs Base64 compatíveis em image_urls. Cada imagem deve cumprir os formatos aceitos e o limite de 10 MB.

Quando escolher 1K ou 2K?

Use 1K para iterações rápidas e materiais sem exigência máxima de detalhes. Escolha 2K para imagens finais com muito texto, bordas finas ou exibição em tamanho grande. Standard tem atualmente o mesmo preço nas duas resoluções, enquanto Pro 2K custa mais do que Pro 1K; avalie latência, qualidade e custo em conjunto.