Como usar a API de texto para imagem grok-imagine-quality: curl, Python e uma requisição pronta para executar

Resumo

• O que é isto: uma solução executável para usar a API grok-imagine-quality/text-to-image no hiapi — crie uma tarefa via POST /v1/tasks, faça polling em GET /v1/tasks/<taskId> (ou use callback) e baixe a imagem de output[0].url.
• schema estrito e enxuto: prompt (obrigatório), aspect_ratio (13 proporções, padrão 1:1), resolution (1k | 2k, minúsculas, padrão 1k), output_format (jpeg | png | webp, padrão jpeg). Qualquer outro campo é rejeitado com 400.
• “Quality” é um nível, não um ajuste. Não existe parâmetro quality nem rich_detail — detalhes, materiais e iluminação mais ricos são exatamente o que esta variante do modelo oferece por padrão. Se você precisa de rascunhos em lote baratos, há o modelo irmão de nível padrão grok-imagine/text-to-image no mesmo endpoint.
• As URLs de saída têm prazo expireAt — baixe ou persista o armazenamento a tempo.

O que você vai construir e do que precisa

Objetivo: enviar um prompt de texto para grok-imagine-quality/text-to-image e obter de volta um arquivo de imagem finalizado, utilizável como visual principal — primeiro com curl, depois como um pequeno script Python que pode entrar na fila de tarefas.

Você só precisa de uma coisa: uma chave de API do hiapi. Obtenha-a no seu console do hiapi e exporte:

export HIAPI_API_KEY="sk-..."

Toda requisição é autenticada com o cabeçalho bearer padrão: Authorization: Bearer sk-<key>.

Requisição mínima executável (curl)

A geração de imagens no hiapi é somente assíncrona. Você não espera uma chamada HTTP longa; em vez disso, cria uma tarefa e busca o resultado quando ela termina.

Passo 1 — criar a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "visual principal de produto de uma máquina de espresso preta fosca sobre bancada de ardósia, iluminação direcionada dramática, profundidade de campo rasa, acabamento comercial premium",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Enquanto o modelo trabalha em segundo plano, você recebe imediatamente um taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

Passo 2 — polling até o estado terminal:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

A tarefa passa por queued → handling → archiving e finalmente chega a success ou fail. Somente success traz saída:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Passo 3 — baixar antes de expireAt:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

O mesmo fluxo em Python

Um script completo — cria, faz polling, salva. Copie, defina HIAPI_API_KEY e execute.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "visual principal de produto de uma máquina de espresso preta fosca sobre bancada de ardósia, "
            "iluminação direcionada dramática, profundidade de campo rasa, acabamento comercial premium"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # minúsculas! "2K" é rejeitado com 400
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # 4xx aqui = a própria requisição foi rejeitada
task_id = resp.json()["data"]["taskId"]
print("Tarefa criada:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png salvo")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Tarefa falhou: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving —— continue o polling

A geração no nível 2k geralmente termina em um ou dois minutos; um intervalo de polling de 5 segundos é suficiente.

Os parâmetros que realmente existem

O schema de entrada é estrito — campos desconhecidos falham com 400 INVALID_REQUEST: additional properties not allowed, em vez de serem silenciosamente ignorados. Isso é bom: erros de digitação não passam despercebidos para produção. Escopo completo da interface:

Campo	Obrigatório	Valores	Padrão
input.prompt	Sim	texto livre	—
input.aspect_ratio	Não	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	1:1
input.resolution	Não	1k, 2k (somente minúsculas)	1k
input.output_format	Não	jpeg, png, webp	jpeg

Três coisas valem saber antes de construir em cima disso:

• O “quality” no nome é um nível, não um parâmetro. Você pode ver este modelo descrito como tendo detalhes, materiais e iluminação mais ricos — isso é a própria variante do modelo. Não há campo rich_detail, quality ou style para alternar.
• 1k e 2k são cobrados em níveis diferentes. Padrão comum: iterar o prompt repetidamente em 1k e depois rodar novamente com o prompt vencedor em 2k para gerar o material final. Consulte o preço atual por imagem na página de preços do hiapi.
• Sem n, sem seed, sem negative_prompt. Uma tarefa gera uma imagem. Para variantes, envie várias tarefas em paralelo — elas são independentes e entram na fila simultaneamente.

Considerações de produção: callbacks, idempotência e erros

Em produção, prefira callbacks ao polling. Passe callback no nível superior do corpo da requisição (não dentro de input) e o hiapi chamará seu serviço quando a tarefa atingir o estado terminal:

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

Com when: "final", tanto success quanto fail são notificados, então deduplique pelo taskId do seu lado. Mantenha um polling de baixa frequência como fallback para o caso de callbacks se perderem — o endpoint de detalhes da tarefa é sempre a fonte da verdade.

Torne as retentativas seguras com Idempotency-Key. A criação de tarefa aceita o cabeçalho Idempotency-Key (até 255 bytes). Repetir com a mesma key nunca cria tarefas duplicadas — a repetição retorna o taskId original:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Diferencie e trate três formas de falha:

1. Falha de autenticação — HTTP 401 e {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Verifique a chave e se ela tem permissão para usar este modelo; não tente novamente às cegas.
2. Entrada inválida — HTTP 400 e "error_code": "INVALID_REQUEST", com a mensagem indicando o campo específico (por exemplo, resolution: value must be one of '1k', '2k'). Corrija o payload; repetir com o mesmo corpo falhará da mesma forma.
3. Falha no nível da tarefa — a chamada de criação é bem-sucedida, mas a tarefa termina com status: "fail" e um objeto data.error. Verifique error.code antes de reenviar.

Atenção ao expireAt. As URLs de saída são temporárias. Baixe o arquivo imediatamente após a tarefa ter sucesso, ou passe storage: "persistent" na criação para manter a saída por longo prazo.

Páginas relacionadas

• Página do modelo grok-imagine-quality/text-to-image — playground e preço por nível
• Referência completa de parâmetros na documentação
• Referência da API de criação de tarefa — headers, idempotência, callbacks
• Como usar grok-imagine-quality para imagem para imagem — o mesmo nível, editando imagens existentes
• Todos os modelos de imagem, vídeo e música

Perguntas frequentes

Qual é a diferença entre grok-imagine-quality e grok-imagine/text-to-image? Mesmo endpoint, mesma estrutura de requisição, níveis diferentes. O nível quality é voltado a visuais principais e materiais comerciais, com detalhes e iluminação mais ricos, com preço por nível de resolução 1k/2k; o grok-imagine/text-to-image padrão é a opção mais rápida e barata para lotes e ideação.

Por que "resolution": "2K" retorna 400? O enum diferencia maiúsculas de minúsculas e usa minúsculas: 1k ou 2k. Valores em maiúsculas são rejeitados com INVALID_REQUEST.

É possível definir um tamanho exato em pixels como 1920x1080? Não. Você controla a forma com aspect_ratio (13 opções, de 2:1 ultrawide a 9:20 vertical alto) e a nitidez com os níveis 1k/2k. Este modelo não tem um campo size livre.

É possível gerar várias imagens em uma única requisição? Não — não há parâmetro n. Envie várias tarefas em paralelo; cada tarefa retorna seu próprio taskId e é processada simultaneamente.

O grok-imagine-quality suporta imagem para imagem? Sim, com um id de modelo separado: grok-imagine-quality/image-to-image. Consulte o schema em solução de imagem para imagem — ele é diferente do texto para imagem.

Quanto tempo dura a URL do resultado? Cada entrada de output[] tem um timestamp Unix expireAt. Baixe antes desse prazo, ou use storage: "persistent" ao criar a tarefa (ou promova a saída posteriormente) para preservá-la.

Como é uma tarefa enfileirada mas não concluída? O GET /v1/tasks/<taskId> retorna status como queued, handling ou archiving, ainda sem output. Somente success contém saída baixável; fail contém data.error.