API de texto para imagem GPT Image 2.5 Sunburst: guia prático com curl e Python

Se você quer gerar imagens através da API do hiapi usando gpt-image-2.5-sunburst/text-to-image, este guia vai conduzi-lo por uma requisição completa e funcional, usando tanto curl quanto Python — desde a criação da tarefa até o download da URL final da imagem. Cada requisição/resposta mostrada aqui foi executada de fato contra a API em produção antes da publicação.

Pré-requisitos

• Uma conta hiapi e uma chave de API (sk-...). Obtenha-a no console do hiapi.
• curl, ou Python 3.8+ se você for acompanhar o exemplo em Python.
• Orçamento para pelo menos uma imagem de saída. gpt-image-2.5-sunburst/text-to-image é cobrado por resolução de saída — consulte a precificação atual antes de rodar em produção, pois as tarifas podem mudar.

Todas as requisições usam os cabeçalhos padrão:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

Exemplo mínimo funcional

Os modelos de imagem do hiapi funcionam todos sobre a mesma API de tarefas assíncronas: você cria uma tarefa via POST, depois faz polling (ou recebe via callback de webhook) até ela atingir o estado final e lê a URL da imagem em output[0].url.

1. Criar a tarefa (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

Uma chamada bem-sucedida retorna apenas um ID de tarefa — a geração é assíncrona:

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

2. Consultar o resultado

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01ABCDEF..." \
  -H "Authorization: Bearer sk-your-api-key-here"

Consulte repetidamente a cada poucos segundos até data.status atingir um valor final. Em caso de sucesso, a resposta se parece com isto (taskId/URL encurtados para facilitar a leitura):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Obtenha a imagem em data.output[0].url. Essa URL expira (veja expireAt, um timestamp Unix) — após o sucesso da tarefa, baixe os bytes imediatamente e armazene-os você mesmo; não a trate como um link permanente.

3. Exemplo completo em Python

import time
import requests

API_KEY = "sk-your-api-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

Quais campos input realmente aceita

O schema de gpt-image-2.5-sunburst/text-to-image é pequeno e rigoroso. Apenas os campos abaixo são aceitos — qualquer outro campo (quality, size, n, output_format, style, seed) é rejeitado com 400:

Campo	Obrigatório	Valores
prompt	Sim	Qualquer string
resolution	Não (padrão 1K)	1K, 2K, 4K
aspect_ratio	Não	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9
background	Não	transparent, opaque, auto

Observe que esse schema é diferente do modelo bruto gpt-image-2.5-sunburst: este último aceita níveis de quality (low/medium/high/xhigh/max/auto) e suporta edição imagem-para-imagem via image_urls. A precificação dos dois também é diferente — antes de confiar em números específicos, verifique em /en/pricing, pois as tarifas podem mudar.

Padrões para produção

Usar callback de webhook em vez de polling

Para qualquer cenário além de scripts rápidos, abandone o polling e deixe o hiapi chamar você quando a tarefa terminar. Adicione um objeto callback de nível superior à mesma requisição POST /v1/tasks:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-app.example.com/webhooks/hiapi",
    "when": "final"
  }
}

when: "final" é o único valor suportado atualmente — quando a tarefa atinge o estado final (success ou fail), seu endpoint é chamado uma vez, com um payload de estrutura idêntica ao resultado obtido via polling.

Polling vs. callback: o polling é mais fácil de implementar corretamente em scripts ou notebooks e não exige um endpoint público, mas desperdiça requisições e adiciona latência (em média, o seu intervalo de polling) até você saber que terminou. Para integrações de servidor ou qualquer cenário de alta concorrência, o callback é mais adequado — você evita completamente o loop de polling e é notificado assim que a tarefa é concluída.

Idempotência em retentativas

A API de tarefas aceita uma string idempotency_key de nível superior, ao lado de model/input/callback. Se seu cliente pode repetir o POST após um timeout (você enviou a requisição, mas nunca recebeu resposta), anexe uma chave estável para ter um sinal claro de verificação em vez de adivinhar se a requisição original foi realmente processada.

Tratamento de erros

Uma chave de API inválida ou expirada retorna HTTP 401 e um corpo de erro estruturado:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

Valores de input inválidos (membro de enum incorreto, prompt ausente, campos não suportados) retornam HTTP 400 antes de criar a tarefa — portanto, você não é cobrado:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Verifique explicitamente os dois casos: repita em erros transitórios de rede/5xx, mas trate o 400 como um sinal para corrigir o corpo da requisição, não como algo a repetir às cegas.

Recursos relacionados

• Página do modelo gpt-image-2.5-sunburst — referência completa de parâmetros e precificação em tempo real para o modelo bruto e a rota /text-to-image.
• Precificação do hiapi — tarifas atuais por resolução deste e de todos os outros modelos.
• Receitas de prompts para GPT Image 2.5 Sunburst — se você procura inspiração antes de começar a escrever seu script, aqui há exemplos de prompts para consultar.

Perguntas frequentes

Preciso especificar resolution? Não — se omitido, o padrão é 1K. Se você precisa de saída em 2K ou 4K, defina explicitamente, pois o preço aumenta com a resolução.

Posso passar quality como na documentação de outros modelos GPT Image? Nesta rota, não. gpt-image-2.5-sunburst/text-to-image rejeita totalmente quality — esse parâmetro existe apenas no ID do modelo bruto gpt-image-2.5-sunburst, que tem schema e precificação diferentes.

Por que minha requisição retorna um ID de tarefa em vez da imagem diretamente? Todos os modelos de imagem no hiapi funcionam pela mesma API de tarefas assíncronas (POST /v1/tasks → polling ou callback → output[0].url), independentemente da velocidade real do modelo subjacente. Construa a integração uma vez em torno desse padrão e cada modelo que você trocar depois funcionará da mesma forma.

O que acontece se eu não baixar a URL de saída a tempo? Ela expira — o campo expireAt na resposta da tarefa é o timestamp Unix em que a URL temporária deixa de funcionar. Assim que status for success, baixe e armazene os bytes você mesmo imediatamente.

Posso usar este modelo para edição imagem-para-imagem? Na rota /text-to-image, não. Para edição de imagem, use o ID do modelo bruto gpt-image-2.5-sunburst e passe o campo de entrada image_urls — consulte a página do modelo para o schema exato.

Pronto para tentar por conta própria? Obtenha uma chave de API no console do hiapi e substitua o prompt no exemplo em Python acima.