Como usar a API de geração de imagem do Grok Image 2.0? Gere sua primeira imagem em 5 minutos

Como usar a API de geração de imagem do Grok Image 2.0? Três passos: POST /v1/tasks para criar a tarefa, obter o taskId e então fazer polling (ou definir um callback), e baixar a imagem gerada a partir de data.output[0].url. Custa $0,052 por imagem, e 1K e 2K têm o mesmo preço.

O Grok Image 2.0 já está disponível na HiAPI. Abra a página do modelo para gerar diretamente; novos usuários ganham 200 créditos ao se registrar, o suficiente para gerar 1 imagem e ver o resultado.

TL;DR

• O que é: grok-imagine-image-2.0/text-to-image, o modelo de geração de imagem da xAI, que usa a interface unificada de tarefas assíncronas da HiAPI.
• Quanto custa: $0,052 por imagem, o mesmo preço para 1K / 2K, low / medium e qualquer proporção; a cobrança é por imagem gerada com sucesso, e falhas são reembolsadas automaticamente. Com $10 dá para gerar cerca de 192 imagens.
• Como chamar mais rápido: basta um prompt para gerar a imagem; opcionalmente há três parâmetros: aspect_ratio, resolution e quality.

Quais são os parâmetros da geração de imagem do Grok Image 2.0?

O input tem apenas quatro campos:

Campo	Obrigatório	Valores	Descrição
prompt	Sim	String	Descrição da imagem
aspect_ratio	Não	1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20、auto	Padrão 1:1
resolution	Não	1k、2k	Padrão 1k
quality	Não	low、medium	Padrão medium; medium tem mais detalhes, low é mais rápido

Cada tarefa gera 1 imagem; para gerar em lote, envie várias tarefas em paralelo. Campos ou valores fora da tabela acima retornam 400, e a mensagem de erro indica o campo específico.

Duas opções: teste online e integração via API

Teste online (1 minuto)

1. Abra a página do modelo de geração de imagem e faça login.
2. Digite o prompt e escolha a proporção e a resolução.
3. Clique em 「Executar」, e após a tarefa concluir com sucesso, visualize e baixe a imagem gerada.

Integração via API (5 minutos)

1. Crie uma API Key no console.
2. Envie a tarefa com POST /v1/tasks.
3. Faça polling em GET /v1/tasks/<taskId>, ou configure um callback.
4. Após o sucesso, baixe imediatamente data.output[0].url.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Primeiro, pegue um prompt que funcione: o abaixo gera uma imagem de produto em 3:2. Gerar com este prompt → (escolha proporção 3:2 e resolução 2K)

curl e Python: gere a primeira imagem

Primeiro, defina a API Key:

export HIAPI_API_KEY="sk-..."

Todas as requisições levam Authorization: Bearer sk-<key>. A geração de imagem é assíncrona e usa a mesma interface de tarefas dos outros modelos da HiAPI.

Passo 1, criar a tarefa:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Retorna o taskId imediatamente:

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

Passo 2, fazer polling até o estado final:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Verifique data.status: success indica sucesso, fail indica falha; nos demais estados, continue aguardando. Exemplo de resposta de sucesso:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Atenção a storage: "temp" e expireAt: o endereço da imagem gerada é temporário. Baixe-a imediatamente após a conclusão da tarefa, ou transfira-a para seu próprio armazenamento de objetos.

Versão em Python:

Primeiro instale o requests (python3 -m pip install requests) e defina o HIAPI_API_KEY acima. O script faz polling por no máximo 10 minutos; após o timeout, guarde o taskId e continue consultando.

import os
import time
import requests

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


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

O que observar antes de ir para produção?

• Para lotes, use callback, não polling em loop apertado. Inclua callback ao criar a tarefa, e após o término a HiAPI envia um push para o seu endereço:

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

  when: "final" notifica quando a tarefa atinge o estado final de sucesso ou falha, e o receptor deduplica por taskId. Use polling para páginas interativas e callback para processamento em lote.

• Transfira a imagem imediatamente. data.output[0].url é um endereço temporário e expira conforme expireAt.

• Envie cada tarefa apenas uma vez. Após receber a resposta, salve a correspondência entre o taskId e a tarefa do seu negócio; reenvios podem criar várias tarefas e cobrar cada uma. Se a requisição de criação der timeout sem receber o ID, verifique primeiro o registro de tarefas antes de decidir se reenvia.

• Especifique resolution explicitamente. O padrão é 1k; 1K e 2K têm o mesmo preço, então para a versão final envie direto "resolution": "2k".

• Use quality: low para ajustar o prompt. Mesmo preço e retorno mais rápido; mude para medium na versão final.

• Tratamento de erros. Verifique primeiro o status HTTP e o code e message da resposta, depois leia data. Erros de parâmetro ou autenticação devem ser corrigidos antes de reenviar; quando a tarefa retornar fail, registre o erro e pare o polling.

Leitura relacionada

• Quanto custa a API do Grok Image 2.0? Geração de imagem por $0,052 a imagem, sem acréscimo para 2K
• Prompts de geração de imagem do Grok Image 2.0: 5 cenários para copiar e gerar
• Integração da API de imagem para imagem do Grok Image 2.0: editar com uma única imagem de referência
• Grok Image 2.0 vs GPT Image 2: comparação com o mesmo prompt
• Autenticação e Início rápido

Perguntas frequentes

Como escrever o ID do modelo? Escreva o grok-imagine-image-2.0/text-to-image completo, mantendo o número de versão 2.0 e /text-to-image.

O que fazer ao receber "additional properties not allowed"? O input aceita apenas os quatro campos prompt, aspect_ratio, resolution e quality. Campos comuns em outros modelos, como size, n, seed, negative_prompt e output_format, não estão disponíveis aqui; basta removê-los.

É possível gerar várias imagens de uma vez? Não, cada tarefa gera 1 imagem. Para várias imagens, envie várias tarefas em paralelo.

Por quanto tempo o endereço de saída é válido? É armazenamento temporário; o expireAt na resposta é um timestamp Unix. Baixe ou transfira a imagem imediatamente após o sucesso da tarefa.

É preciso esperar o resultado de forma síncrona? Não. A interface de criação retorna imediatamente após a tarefa entrar na fila; scripts curtos fazem polling em GET /v1/tasks/<taskId>, e ambientes de produção configuram callback.

Tarefas com falha são cobradas? Não; a cobrança é por imagem gerada com sucesso, e falhas são reembolsadas automaticamente. Quando data.status for fail, pare o polling.

Gere sua primeira imagem agora

Primeiro defina o HIAPI_API_KEY, crie a tarefa com o curl acima e consulte com o data.taskId retornado; após o sucesso da tarefa, baixe a partir de data.output[0].url. Se quiser ver o resultado primeiro, abra a página do modelo de geração de imagem: os 200 créditos de boas-vindas são suficientes para 1 imagem.