WaveSpeedAI

Como Usar a API Z-Image-Turbo no WaveSpeed (Guia Passo a Passo)

Como Usar a API Z-Image-Turbo no WaveSpeed (Guia Passo a Passo)

Uma pequena coisa me trouxe aqui. Sou Dora. Naquele dia, eu precisava de uma foto de produto limpa para uma variação de página de destino, e minhas ferramentas de imagem usuais pareciam mais pesadas que a tarefa. Eu continuava ouvindo falar sobre a Z-Image-Turbo​ ​​​API​. Não o tipo de menção barulhenta, mais como se aparecesse silenciosamente em changelogs e notas de engenharia. Então eu tentei.

Usei ao longo de uma semana no final de janeiro de 2026, principalmente para gerar visuais de marketing simples e algumas texturas de conceito para um protótipo. Nada sofisticado. Eu queria ver onde se encaixava sem refazer minha stack. Aqui está o que ajudou, o que não ajudou e como conectei tudo sem criar uma bagunça.

Pré-requisitos

Criar Conta WaveSpeed

Comecei criando uma conta WaveSpeed. O fluxo era básico: email, senha, verificação. Sem surpresas. Gosto que o painel não tentou me vender nada antes que eu pudesse testar.

Obter Sua Chave API

Após o cadastro, fui à seção de desenvolvedor e gerei uma chave. Rotulei para meu projeto de teste e armazenei em meu arquivo .env local. Uma pequena observação: criei uma segunda chave para testes posteriores. Manter as chaves limitadas por ambiente me salvou de adivinhar quais chamadas estavam atingindo meu plano pago.

Fundamentos da API

Estrutura da URL do Endpoint

Usei um único endpoint de geração para a maioria dos casos. O padrão ficava assim:

  • Base: api.wavespeed.ai
  • Caminho versionado: /v1
  • Caminho do produto: /z-image-turbo
  • Ação: /generate

Então uma URL típica ficava assim /v1/z-image-turbo/generate. Evito codificar versões porque elas mudam. Coloquei a base e versão em config para poder atualizá-la depois sem reescrever as chamadas.

Configuração do Header de Autenticação

Auth era um token Bearer padrão. O que ajudou foi manter a configuração do header centralizada:

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

Testei com um timeout pequeno (10s) primeiro, depois aumentei. Quando o serviço está sob carga, a geração de imagem pode levar mais tempo que uma chamada REST típica. Melhor planejar para isso do que fazer novas tentativas agressivas e atingir limites de taxa.

Parâmetros Principais Explicados

prompt, Escrevendo Prompts Efetivos

Não sou um poeta de prompts. O que funcionou aqui era linguagem simples e literal e uma única dica de estilo clara. Para fotos de produtos, encontrei uma estrutura constante:

  • Assunto: “um fone de ouvido sem fio preto fosco em fundo branco contínuo”
  • Ângulo ou lente: “ângulo de 45 graus, iluminação suave de estúdio”
  • Dicas de contexto: “sombra mínima, sem reflexos”

Evitei amontoar estilos (“cinemático, melancólico, editorial, brilhante”) porque as imagens se desviavam. Prompts curtos e simples deram resultados mais previsíveis.

Duas passagens me ajudaram a iterar:

  • Primeira passagem: prompt amplo para ver a composição.
  • Segunda passagem: adicionar restrições apenas onde necessário (comprimento da sombra, textura de fundo).

size, Resoluções Suportadas (256-1536)

Usei tamanhos quadrados e retrato principalmente. A API aceitava valores comuns de 256 até 1536. Fiquei com 512 para visualizações rápidas e 1024 para ativos finais. 1536 produzia um bom detalhe, mas custava mais tempo e tokens. Se você está gerando muitas variantes, comece pequeno e aumente a escala ou re-execute prompts selecionados em um tamanho maior.

seed, Controle de Reprodutibilidade

A seed importou mais do que eu esperava. Quando encontrei um visual que gostava, salvei a seed para que pudesse ajustar apenas uma variável (como densidade de fundo) sem me desviar muito. Se mudei o prompt bastante, limpei a seed para evitar lutar contra o viés anterior do modelo. Na prática: registrei prompt, tamanho e seed por ID de imagem. Tornou as re-renderizações chatas, de um jeito bom.

output_format, JPEG vs PNG vs WebP

  • JPEG: leve e rápido. Bom para visualizações e ativos web sem transparência.
  • PNG: ​sem perda, maior. Usei para sobreposições de UI ou quando precisava de uma borda limpa.
  • WebP: ​um bom termo médio. Menor que PNG, mais limpo que JPEG agressivo.

Quando estava fazendo lotes, defini visualizações para JPEG e finais para PNG ou WebP dependendo do alvo. Misturar formatos em uma execução é possível, mas mantive consistente por trabalho para reduzir a administração.

Exemplos de Código

Início Rápido com cURL Aqui está o caminho mais curto que usei para verificar o endpoint. Gosto de começar com cURL porque deixa as mensagens de erro óbvias.

Bash

curl -X POST https://api.wavespeed.ai/v1/z-image-turbo/generate \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "um fone de ouvido sem fio preto fosco em fundo branco contínuo, iluminação suave de estúdio",
    "size": 1024,
    "seed": 12345,
    "output_format": "webp",
    "enable_sync_mode": true
  }' \
  --output preview.webp

Se o modo síncrono estiver habilitado e suportado para sua solicitação, a resposta retorna dados de imagem binária ou um campo base64 (depende dos headers e configurações do servidor). Salvei diretamente em um arquivo durante testes.

Implementação em Python Mantive a versão Python simples. Requests, um timeout e verificações de erro básicas.

Python

import os
import requests
import base64

API_KEY = os.getenv("WAVESPEED_API_KEY")
URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate"

payload = {
    "prompt": "canto de leitura aconchegante perto de uma janela, luz suave da manhã, minimalista",
    "size": 1024,
    "output_format": "png",
    "enable_sync_mode": True,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()

# Algumas implementações retornam JSON com base64. Outras retornam binário diretamente.
content_type = resp.headers.get("Content-Type", "")
if "application/json" in content_type:
    data = resp.json()
    img_b64 = data.get("image_base64")
    if not img_b64:
        raise RuntimeError("Nenhuma imagem na resposta")
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(img_b64))
else:
    with open("output.png", "wb") as f:
        f.write(resp.content)

print("Salvou output.png")

Exemplo JavaScript/Node.js Em Node, prefiro fetch com AbortController para timeouts.

JavaScript

import fetch from 'node-fetch';
import { writeFileSync } from 'fs';

const API_KEY = process.env.WAVESPEED_API_KEY;
const URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate";

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);

const payload = {
  prompt: "textura de papel abstrata, fibras suaves, branco puro, grão sutil",
  size: 512,
  output_format: "jpeg",
  enable_sync_mode: true,
};

try {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });

  if (!resp.ok) {
    throw new Error(`${resp.status} ${resp.statusText}`);
  }

  const buffer = Buffer.from(await resp.arrayBuffer());
  writeFileSync("out.jpg", buffer);
  console.log("Salvou out.jpg");
} catch (err) {
  console.error("Falha na solicitação:", err.message);
} finally {
  clearTimeout(timeoutId);
}

Modo Assíncrono vs Síncrono

enable_sync_mode Explicado

Quando enable_sync_mode era verdadeiro, imagens pequenas (512–1024) geralmente chegavam de uma vez. Isso foi bom para visualizações e casos isolados. Mas o modo síncrono esgota o tempo sob carga pesada ou tamanhos maiores. Quando atingi essa borda, a API retornou um job ID em vez de uma imagem.

Pesquisando por Resultados

Async demorou um segundo para conectar, depois ficou bem. O fluxo:

  • POST uma solicitação de geração com enable_sync_mode definido como false (ou apenas omita).
  • Receber um job_id no JSON.
  • Pesquisar um endpoint de status a cada 1–2 segundos com backoff exponencial.
  • Quando o status for concluído, baixar a imagem do URL fornecido.

Limitei a pesquisa a ~30 segundos antes de falhar graciosamente. Em produção, mudaria para um webhook se o serviço o oferecer. Pesquisar funciona, mas não é romântico.

Tratamento de Erros

Códigos de Erro Comuns

O que vi durante testes:

  • 400: um campo ruim (tamanho fora do intervalo, formato desconhecido). Corrija seu payload.
  • 401: token Bearer ausente ou inválido. Verifique o header e o escopo de chave.
  • 404: caminho de endpoint incorreto ou trabalho não encontrado (geralmente um erro de digitação).
  • 429: limite de taxa. Volte atrás e tente novamente mais tarde.
  • 500/503: problema de serviço transitório. Tente novamente com jitter.

Registrei corpos de resposta porque frequentemente carregavam uma dica em linguagem simples, útil quando tamanho ou seed foram rejeitados.

Melhores Práticas de Limite de Taxa

Usei um token bucket no cliente, com uma fila curta. Se a API retornasse 429, eu recuava exponencialmente e adicionava jitter aleatório (50–200ms) para evitar rebanhos trovejantes. Além disso, agrupar solicitações (veja abaixo) reduziu picos de aumento.

Dicas de Produção

Padrão de Processamento em Lote

Gerar uma imagem por solicitação parecia simples, mas desperdiçava sobrecarga. Mudei para um tamanho de lote pequeno (3–5 prompts cada) e obtive taxa de transferência mais estável. Escrevi resultados em uma pasta datada com um arquivo manifest.json que salvava prompt, tamanho, seed e caminho de saída. Esse manifesto foi útil quando um stakeholder disse, “Podemos fazer o mesmo, mas com uma luz mais quente?” Apenas aumentei a seed ou ajustei o prompt e re-executei.

Otimização de Custo

Três coisas importaram:

  • Disciplina de tamanho: visualizar em 512, finalizar em 1024 apenas quando necessário. 1536 apenas para uso pesado de corte.
  • Ajuste de formato: JPEG para visualizações; WebP para a maioria das compilações web; PNG quando a transparência é inegociável.
  • Parada antecipada: se os primeiros frames pareciam errados, cancelava o trabalho em vez de esperar. Economizava centavos, que se acumulam.

Uma nota prática adicional: limitei o gasto diário total em meus scripts. Não é glamouroso, mas me protegeu de um loop descontrolado.

Algumas observações de fechamento. A Z-Image-Turbo API não parecia mágica. Provavelmente é por isso que gostei dela. Foi constante assim que defini os guardrails: seeds fixas para reprodutibilidade, pequenos lotes, timeouts conservadores. O modo síncrono foi bom para visualizações; assíncrono fez sentido para todo o resto. Se você já está nadando em ferramentas de IA, essa não gritará por atenção. Ficará silenciosamente no pipeline e fará seu trabalho.

Ainda tenho curiosidade sobre como ela lida com prompts barulhentos em resoluções mais altas. Esse é um teste para outro dia.