Gerar imagens de produtos de e-commerce com grok-imagine/text-to-image através da API hiapi

A maioria dos pipelines de imagens de produtos quebra quando precisa gerar três formatos diferentes a partir da mesma foto — uma imagem quadrada para a grade do catálogo, um recorte vertical para a página de detalhes do produto (PDP) no mobile e uma imagem ampla para o banner principal da página inicial. Recortar uma imagem principal raramente fica bom em todas as proporções — o produto acaba cortado ou surgem áreas vazias estranhas. O grok-imagine/text-to-image evita esse problema: ele gera nativamente nas proporções que você precisa, incluindo dois formatos amplos criados especificamente para esse tipo de trabalho com banners (2:1 e 20:9), com preço uniforme de $0.03 por imagem na API hiapi, sem variação por resolução.

Este guia apresenta a estrutura real da requisição, as armadilhas de schema que encontramos nos testes, um script de geração em lote que executa uma lista completa de tomadas para um único briefing de produto e uma contabilização honesta de custos para escala de catálogo.

Posicionamento de preço

Verificado na página de preços da hiapi no momento da redação:

Modelo	Preço por imagem	Resolução	Controle de proporção
grok-imagine/text-to-image	$0.03 uniforme	1K ou 2K, mesmo preço	13 proporções, incluindo 2:1, 20:9
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	Preço escalonado por resolução	Mesmo conjunto de proporções

A camada de qualidade realmente traz melhorias significativas em detalhes finos — reflexos, textura de tecido, textos pequenos — e vale o custo extra para um pequeno número de imagens principais realmente importantes. Para a maior parte das imagens de um catálogo (miniaturas de grade, variações de lifestyle, outros ângulos), o modelo base já é suficientemente próximo, e a diferença de preço de 2 a 3 vezes não se justifica em cenários de lote.

A requisição que realmente funciona

Todas as imagens desta página vêm do mesmo endpoint:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Isso retorna um taskId; faça polling em GET /v1/tasks/{taskId} até que status seja success, então obtenha output[0].url e baixe — essa URL é assinada e expira, portanto salve os bytes imediatamente em vez de linkar diretamente para ela.

Durante os testes, três detalhes de schema nos pegaram de surpresa e vale a pena conhecer antes de construir sua própria integração:

• aspect_ratio é um enum estrito de 13 valores, não um formato livre. Enviar qualquer outro valor retorna 400 com a lista completa: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. As duas proporções necessárias para banners são 2:1 e 20:9 — a maioria dos modelos de imagem na hiapi vai no máximo até 21:9, ou não oferece opção ultrawide.
• resolution aceita apenas minúsculas — use "2k", não "2K". Enviar a forma maiúscula é rejeitado diretamente, em vez de convertido silenciosamente.
• O schema de entrada é estrito. Campos extras ou com erro de digitação (um negative_prompt residual, uma chave style copiada de exemplos de outros modelos) fazem a requisição inteira falhar, em vez de serem ignorados.

Escrever prompts para imagens limpas em escala de catálogo

A maior alavanca para obter saída consistente de catálogo é declarar explicitamente o que você não quer. Para a imagem principal em fundo branco acima, o prompt eficaz é:

"Porta-filtro de café cerâmico fosco sobre fundo branco contínuo, iluminação de softbox de estúdio, centralizado, sem gradiente de sombra além da sombra suave de contato, sem texto, sem marca d'água, sem adereços, fotografia de produto de e-commerce, foco nítido"

Para variações de lifestyle usadas em imagens secundárias de PDP ou banners de e-mail, troque o fundo e as pistas de iluminação, mas mantenha a mesma disciplina de "sem texto / sem marca d'água / sem adereços além dos especificados" — é exatamente isso que impede o grok-imagine de adicionar objetos desordenados ou texto de rótulo ilegível no próprio produto:

"O mesmo porta-filtro cerâmico sobre uma bancada de cozinha de madeira, ao lado de uma caneca fumegante, luz da manhã quente, profundidade de campo rasa, fundo de cozinha aconchegante e cotidiano suavemente desfocado, sem texto, sem logotipo"

Fluxo de trabalho para banners ultrawide

Quando a necessidade é um banner de página inicial ou de categoria, e não uma miniatura de catálogo, 2:1 e 20:9 são justamente as duas proporções que tornam o grok-imagine particularmente digno de adoção. O truque é indicar diretamente o espaço negativo, em vez de esperar que o recorte caia bem — descreva onde o produto está no quadro e quais áreas devem ficar vazias:

"Porta-filtro de café cerâmico fosco posicionado no terço direito do quadro, luz externa da hora dourada, amplo espaço negativo vazio nos dois terços esquerdos da imagem para sobreposição de texto de título, composição cinematográfica ampla, sem texto, sem logotipo"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Se o seu CMS exige dimensões exatas em pixels em vez de proporção, gere na proporção suportada mais próxima e depois recorte sem perdas a partir dessa imagem — para cálculos específicos de preenchimento, consulte as nossas notas sobre dimensões exatas via API.

Gerar uma lista completa de tomadas em lote

Um único briefing de produto normalmente exige mais de uma imagem. O script abaixo reproduz o script real usado para gerar as quatro imagens desta página — submete uma tarefa por imagem, faz polling até a conclusão e salva em disco:

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Se você for executar um lote completo de vários SKUs, submeta todas as três tarefas primeiro e então faça polling delas em paralelo (um pequeno asyncio ou pool de threads já resolve) — cada tarefa normalmente conclui em menos de um minuto, e executá-las em série só acumula tempo ocioso de espera sem motivo.

O custo de uma execução real de catálogo

Com $0.03 uniforme por imagem, a combinação de três imagens acima (principal + lifestyle + banner) custa $0.09 por SKU. Em escala:

• 50 SKUs × 3 imagens = 150 imagens → $4.50
• 500 SKUs × 3 imagens = 1.500 imagens → $45
• Adicionar o upgrade grok-imagine-quality apenas para as imagens principais em 2K ($0.10 em vez de $0.03) leva o total de 500 SKUs para $80 — ainda uma fração do custo de uma única sessão fotográfica tradicional de produto.

grok-imagine versus o restante da linha de produtos

Se uma imagem precisa ganhar movimento — por exemplo, um clipe curto de produto de 6 segundos para anúncio em redes sociais em vez de um banner estático —, a mesma família é coberta pelo grok-imagine-image-to-video, que usa uma dessas imagens estáticas como quadro inicial; abordamos esse fluxo de trabalho separadamente no guia de vídeos curtos. Para equipes que comparam com um pipeline de catálogo baseado em Nano-Banana, o nosso guia de e-commerce com Nano-Banana é a referência lado a lado mais próxima — mesma estrutura de API de tarefas, pontos fortes de modelo diferentes.

Perguntas frequentes

O grok-imagine/text-to-image suporta imagem de referência (i2i), e não apenas prompt de texto? Sim — mas essa é uma variante separada do modelo (grok-imagine/image-to-image), com schema de entrada próprio. Este guia cobre apenas o caminho puramente texto-para-imagem.

Por que minha requisição retorna 400 e um erro de "additional properties"? O schema de entrada é estrito. Verifique cuidadosamente se você envia apenas prompt, aspect_ratio e, opcionalmente, resolution — não carregue campos extras copiados de exemplos de outros modelos.

Posso obter uma proporção exata como 1200×630, em vez de escolher do enum? Gere na proporção suportada mais próxima (16:9 chega perto de muitos formatos de banner web) e depois recorte sem perdas no pós-processamento — para o método específico de preenchimento, consulte o guia de dimensões exatas linkado acima.

A resolução 2K vale a espera em relação à 1K? Neste modelo, ambas as resoluções têm o mesmo preço, então use 2K por padrão, a menos que você tenha um orçamento de latência rígido — você ganha mais detalhes de graça.

Experimente você mesmo

Todo o acesso à API aqui funciona com uma chave hiapi padrão — consulte a documentação para autenticação e a referência completa de polling de tarefas, e confira a página de preços para as tarifas mais recentes de toda a linha de modelos antes de se comprometer com execuções em lote.