Como usar o gpt-image-2.5-sunburst pela API hiapi: curl, Python e exemplos de requisição disponíveis

Para gerar ou editar imagens com gpt-image-2.5-sunburst, envie a tarefa com o prompt para POST /v1/tasks e depois consulte GET /v1/tasks/<id> (ou receba um callback) até a tarefa ser concluída, lendo a URL da imagem em data.output[0].url. Este guia cobre a requisição mínima, o conjunto completo de parâmetros e os padrões de produção necessários antes de ir ao ar (callback, idempotência, tratamento de erros).

Pré-requisitos

Você precisa de uma chave de API hiapi. Crie uma no console — cada requisição é autenticada com Authorization: Bearer sk-<your-key>. Não existe um nível gratuito para chamá-la pelo navegador nem uma forma sem chave; todos os exemplos abaixo pressupõem que você já tem uma chave.

Exemplo mínimo funcional

gpt-image-2.5-sunburst/text-to-image exige apenas prompt em input. A proporção padrão é auto e a resolução padrão é 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Ele retorna imediatamente um id de tarefa:

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

Consulte o resultado:

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

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

A versão em Python do mesmo fluxo de ida e volta:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url aponta para armazenamento temporário — a resposta inclui expireAt (segundos Unix). Baixe os bytes e persista-os antes desse prazo (seu próprio armazenamento, S3, R2 etc.); não a trate como um link permanente.

Referência completa de parâmetros

gpt-image-2.5-sunburst tem dois ids de modelo: gpt-image-2.5-sunburst/text-to-image para gerar a partir de um prompt e gpt-image-2.5-sunburst/image-to-image para editar ou compor imagens de referência. Ambos aceitam os mesmos campos; a diferença é que image_urls é obrigatório no image-to-image e não é usado no text-to-image:

Campo	Tipo	Padrão	Descrição
prompt	string, 1–8000 caracteres	—	Obrigatório. Para edições, descreva o que deve mudar e o que deve permanecer exatamente igual.
image_urls	array de URLs	—	Apenas image-to-image, obrigatório, 1–16 imagens JPEG, PNG ou WebP, cada uma com no máximo 20 megapixels e não mais de 30 MB. Deve ser uma URL publicamente acessível ou um data URI.
aspect_ratio	enum	"auto"	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.
resolution	enum	"1K"	1K, 2K, 4K. Isso determina o preço.
background	enum	nenhum	transparent, opaque, auto. transparent só funciona em 1K, quando retorna um PNG com canal alfa.

Exemplo de edição — passe uma ou mais imagens de referência e descreva apenas a alteração desejada:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

O schema é estrito (additionalProperties: false) — campos desconhecidos são rejeitados, então não reaproveite parâmetros de outros modelos de imagem (como size, strength, n).

Padrões de produção

Use callbacks em vez de polling em um backend real. Adicione um bloco callback para pular o loop de polling:

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

when: "final" dispara exatamente uma vez quando a tarefa atinge um estado terminal (success ou fail). Seu endpoint deve retornar 2xx rapidamente e executar o trabalho real de forma assíncrona (baixar a saída, atualizar seu próprio banco de dados) — a hiapi tenta novamente callbacks que não recebem uma confirmação rápida.

Torne as tentativas novamente idempotentes. Se a requisição do cliente der timeout, você não sabe se a tarefa foi criada. Envie o cabeçalho Idempotency-Key na requisição de criação (até 255 bytes) e reutilize a mesma chave ao tentar novamente: apenas uma tarefa é criada para a mesma conta e chave, e a nova tentativa retorna o taskId original. Sem isso, reprocessar o mesmo prompt é cobrado duas vezes.

Trate os estados terminais que você realmente vai encontrar:

• success — leia data.output[0].url e baixe imediatamente (respeitando expireAt).
• fail — verifique data.error antes de tentar novamente para entender o motivo da falha; não repita cegamente a cada falha, pois algumas são problemas no nível do prompt (por exemplo, violação de política) e repetir exatamente igual continuará falhando.
• Consultar um id de tarefa inexistente (erro de digitação, expirado) retorna HTTP 404 com o corpo {"code":404,"message":"task not found"}.

Falhas de autenticação são HTTP 401, não um erro no nível da tarefa:

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

Verifique isso no seu tratamento de erros antes de assumir que a tarefa falhou — uma chave inválida ou revogada nem chega à etapa de criação da tarefa.

Leituras relacionadas

• Página do modelo GPT Image 2.5 Sunburst — exemplos ao vivo e preços atuais.
• GPT Image 2.5: geração, edição e migração — se você está migrando de rotas mais antigas do Image 2 para a linha 2.5 (Flare ou Sunburst), este artigo cobre as diferenças de parâmetros.
• Como reestilizar imagens com IA — se o modo de edição do Sunburst é apenas parte do seu pipeline, aqui há um passo a passo mais amplo de image-to-image.
• Documentação de autenticação e início rápido para entender o ciclo de vida completo de uma requisição além deste modelo específico.

Perguntas frequentes

O gpt-image-2.5-sunburst suporta edição de imagens ou apenas geração a partir de texto? Suporta ambos, por meio de dois ids de modelo. Use gpt-image-2.5-sunburst/image-to-image com image_urls (1–16 imagens de referência) para editar ou compor, e gpt-image-2.5-sunburst/text-to-image para gerar apenas a partir de texto.

O que acontece se eu enviar um array image_urls vazio em vez de omiti-lo? Não faça isso. No image-to-image, image_urls é obrigatório e exige pelo menos uma URL. Para geração puramente textual, use o id de modelo text-to-image.

Quanto custa uma imagem? Depende de resolution: US$ 0,05 para 1K, US$ 0,08 para 2K e US$ 0,12 para 4K, o mesmo para text-to-image e image-to-image. Durante a promoção do Dia do Programador (até 9 de novembro de 2026, 00:00 UTC+8), todos os níveis têm 50% de desconto: US$ 0,025, US$ 0,04 e US$ 0,06. Antes de escalar, consulte a página do modelo para ver os preços atuais.

Posso obter dimensões fixas em pixels em vez de proporção? Sim — além de strings de proporção como 16:9, aspect_ratio também aceita dimensões literais como 1024x1024, 1536x1024 ou 3840x2160.

Por que recebo 404 ao consultar a tarefa? Ou o taskId tem um erro de digitação, ou o endpoint/região que você está consultando não tem essa tarefa. Verifique com cuidado o id que você salvou da resposta de criação — a hiapi não expira silenciosamente registros de tarefas em nenhuma janela normal de polling.

Posso chamá-lo sem uma chave de API para testar? Não. Toda requisição a /v1/tasks exige Authorization: Bearer sk-<key>; não há modo anônimo nem apenas de navegador.