API de imagens Grok Imagine: texto para imagem, imagem para imagem e Quality

Pontos principais

• A API de imagens Grok Imagine no HiAPI tem quatro endpoints: versão padrão e Quality, cada versão oferecendo texto para imagem e imagem para imagem. A estrutura de requisição das quatro é idêntica, apenas o id do modelo difere.
• A versão padrão custa $0.03 por imagem tanto em resolução 1K quanto em 2K. A Quality custa $0.07 em 1K e $0.10 em 2K. O modo imagem para imagem cobra uma pequena taxa adicional por imagem de referência (1–3 referências).
• Com o mesmo prompt, a versão padrão desenhou um cone comum, sem alça e sem nervuras de escoamento; a Quality desenhou um coador de café pour-over reconhecível. Você pode usar a versão padrão para rascunhos e para lidar com grandes lotes, e a Quality para produzir o resultado final.Abra a página do modelo de texto para imagem e experimente; novas contas ganham 200 créditos grátis.

Qual endpoint usar

ID do modelo	Entrada	Preço por imagem	Cenário de uso
grok-imagine/text-to-image	Prompt	$0.03 (1K e 2K)	Rascunhos, geração em lote, banners ultralargos
grok-imagine-quality/text-to-image	Prompt	$0.07 (1K) / $0.10 (2K)	Imagens finais de produto, detalhes e materiais
grok-imagine/image-to-image	Prompt + 1–3 imagens	$0.03 + $0.003 por imagem de referência	Compor produtos em cenas, edição de imagens em lote
grok-imagine-quality/image-to-image	Prompt + 1–3 imagens	$0.08 (1K) / $0.10 (2K) + $0.015 por imagem de referência	Rerrealçar iluminação e mudar de estilo mantendo o sujeito idêntico

Preços em tempo real do HiAPI, consultados em 19 de outubro de 2026. Tarefas com falha não são cobradas.

A edição com uma única imagem de referência custa $0.033 na versão padrão e $0.095 na Quality 1K. Para conhecer a série completa, incluindo vídeo e Grok Imagine Image 2.0, consulte Preços da API Grok Imagine.

Mesmo prompt, versão padrão vs Quality

1:1, 2K, PNG, executado uma vez cada:

matte ceramic pour-over coffee dripper on a pure white seamless background, studio softbox lighting, centered, no shadow gradient beyond a soft contact shadow, no text, no watermark, no props, e-commerce product photography, sharp focus

Versão padrão:

grok-imagine/text-to-image, 1:1, 2K, 2048×2048, $0.03, cerca de 80 segundos.

Quality:

Gerar este prompt no Quality →

grok-imagine-quality/text-to-image, 1:1, 2K, 2048×2048, $0.10, cerca de 78 segundos.

Onde está a diferença:

• O objeto em si: a versão padrão renderizou um cone limpo, mas genérico, que lembra mais uma tigela do que um coador. A Quality desenhou as peças que o tornam um coador pour-over: as nervuras espirais internas, a alça e a base com orifício de drenagem.
• Ambas seguiram as exigências de fundo: branco puro, centralizado, apenas uma sombra de contato suave, sem adereços nem texto.
• Tamanho e velocidade idênticos: ambas retornaram imagens 2048×2048 em cerca de 80 segundos. O que muda entre os níveis é o detalhe, não o tamanho da saída.

Para produtos conhecidos, vale a pena pagar os $0.07 extras pela Quality. Para cenários em que o objeto em si é genérico, como moodboards ou projetos de layout, a versão padrão é suficiente.

Imagem para imagem: coloque seu produto na cena

Passe de 1 a 3 URLs públicas de imagem em image_urls e descreva as alterações necessárias. Quando aspect_ratio é definido como auto (o padrão em imagem para imagem), a saída assume o formato da primeira imagem da lista. O mesmo prompt e as mesmas duas imagens, apenas trocando a ordem, produziram dois recortes diferentes:

grok-imagine/image-to-image, imagem do produto em primeiro lugar, retorna 1248×832 (3:2).

Mesma requisição, imagem da cena em primeiro lugar, retorna 1024×1024 (1:1).

Para controlar o recorte, coloque em primeiro lugar a imagem com o formato desejado ou defina explicitamente aspect_ratio.

No Quality, o ponto forte é mudar uma única coisa mantendo todo o resto igual. Este rerrealce de iluminação preservou o rosto, a jaqueta, a xícara e a composição:

Relight this photo as late golden hour: warm low sun coming from the left,
long soft shadows across the table, amber rim light on her hair and jacket.
Keep her face, expression, pose, the corduroy jacket, the marble table, the
coffee cup and the entire composition exactly the same. Photorealistic, same
camera angle, same framing.

grok-imagine-quality/image-to-image, 1K, auto (entrada 3:2, saída 1248×832), uma imagem de referência, $0.095, 39 segundos.

O padrão que funciona: diga em uma frase o que deve mudar, depois liste tudo o que deve permanecer igual. Para mais receitas, consulte Prompts de imagem para imagem do Grok Imagine Quality.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "A lighthouse on a rocky cliff at golden hour, waves crashing below, photorealistic",
      "aspect_ratio": "2:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Você receberá um taskId. Faça polling em GET https://api.hiapi.ai/v1/tasks/{taskId} até que data.status seja success e então baixe data.output[0].url. O link expira; salve o arquivo imediatamente.

Python: todos os quatro endpoints

# pip install requests; export HIAPI_KEY=your-key first
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, prompt, image_urls=None, timeout_s=300, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    if image_urls:
        body["input"]["image_urls"] = image_urls
    # Reuse the same Idempotency-Key if you retry a submit, so a retry never bills twice
    r = requests.post(API, json=body, headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)  # 400s list every invalid field
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

# Draft on standard, then re-run the keeper on Quality
draft = generate("grok-imagine/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="1k")
final = generate("grok-imagine-quality/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="2k")

# Composite a product into a scene; the first image sets the shape
edit = generate("grok-imagine/image-to-image",
                "Place the product from the first image on the desk in the second image, matching its light",
                image_urls=["https://your-cdn.example.com/product.jpg",
                            "https://your-cdn.example.com/scene.jpg"])

Parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Texto	Escreva aqui tudo o que você quer ou quer evitar
image_urls	Somente imagem para imagem	1–3 URLs	jpeg, png ou webp; SVG não é suportado; cada imagem de referência aumenta o preço
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; imagem para imagem também aceita auto	auto segue a primeira imagem
resolution	Não	1k (padrão), 2k	Minúsculas; afeta o preço somente na Quality
output_format	Não	jpeg (padrão), png, webp

Os formatos ultralargos 2:1 e 20:9 são adequados para banners. Não há 21:9; use 20:9.

Erros que você vai encontrar

Todos os erros abaixo retornam HTTP 400 no envio, portanto nenhuma tarefa é criada e nenhuma cobrança é gerada:

• resolution: value must be one of '1k', '2k': você enviou 2K. Use minúsculas.
• aspect_ratio: value must be one of ...: geralmente é 21:9. Use 20:9.
• additional properties 'n' not allowed (ou seed, negative_prompt, size): esses campos não existem. Uma tarefa gera uma imagem; para várias imagens, envie várias tarefas.
• image_urls: missing required field: imagem para imagem exige pelo menos uma imagem.

Uma chave inválida retorna 401. Falhas após a criação da tarefa aparecem no polling como status: "fail", então verifique data.status, e não apenas o código de status HTTP.

Perguntas frequentes

Usar a versão padrão ou a Quality?

Use a versão padrão para rascunhar por $0.03. Quando o prompt e o layout estiverem viáveis, execute novamente o resultado final na Quality. Na versão padrão, 2K custa o mesmo que 1K, então sempre solicite 2k nela.

É o mesmo que o Grok Imagine Image 2.0?

Não. grok-imagine-image-2.0 é um modelo separado e mais recente, a $0.052 por imagem. Consulte o Guia de texto para imagem do Grok Imagine Image 2.0.

É possível obter várias imagens em uma única requisição?

Não. Não existe o campo n. Envie uma tarefa por imagem; elas serão executadas em paralelo.

Por quanto tempo a saída fica disponível?

O link output[0].url expira. Após o sucesso da tarefa, baixe e armazene por conta própria imediatamente.

Mais saídas reais: imagens de catálogo de produtos com a versão padrão e composição de cenas com fotos de produtos. Sobre vídeo, consulte o Guia da API de vídeo do Grok Imagine.