Como usar gpt-image-2.5-sunburst@pro pela API hiapi: curl, Python e exemplos de requisição executáveis

gpt-image-2.5-sunburst@pro é a rota Pro do modelo gpt-image-2.5-sunburst na hiapi. Este guia leva você do zero até uma requisição executável: qual é exatamente o id do modelo, quais campos input ele aceita, um exemplo curl/Python pronto para rodar e os padrões de produção (idempotência, callbacks, tratamento de erros) de que você precisa antes de rodar sem supervisão.

O que você precisa preparar primeiro

• Uma conta hiapi e uma API key do console. Toda requisição abaixo é autenticada com Authorization: Bearer sk-<your key>.
• É só isso — não é preciso instalar SDK nenhum. Todos os modelos da hiapi são chamados pelo mesmo endpoint de tarefas assíncronas, então, se você já chamou qualquer outro modelo hiapi, a estrutura desta requisição será familiar.

O único ponto específico deste modelo: @pro é um sufixo de rota, não um apelido. A hiapi expõe mais de um modo de chamada para alguns modelos, e gpt-image-2.5-sunburst é um deles — o id de modelo comum e o id com sufixo @pro aceitam campos input diferentes e são cobrados em faixas de preço diferentes. Este guia é específico para gpt-image-2.5-sunburst@pro; usando o id puro gpt-image-2.5-sunburst você obtém um modo e um schema diferentes (veja o FAQ).

Exemplo mínimo executável

Todos os modelos de geração da hiapi — imagem, vídeo ou áudio — são chamados pelo mesmo endpoint unificado: POST /v1/tasks. Você envia model e input, recebe imediatamente um taskId e a geração roda de forma assíncrona.

Para gpt-image-2.5-sunburst@pro, o input aceita:

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	1–32.000 caracteres
image_urls	string[]	Não	1–16 URLs públicas de JPEG/PNG/WebP; inclua este campo para fazer imagem-a-imagem em vez de texto-a-imagem (SVG não é suportado)
aspect_ratio	enum	Não	Por exemplo 1:1, 16:9, 9:16, ou dimensões explícitas como 1536x1024; padrão 1:1
quality	enum	Não	low / medium / high / xhigh / max / auto; padrão medium — antes de aumentar, veja as observações de produção abaixo
background	enum	Não	transparent, opaque ou auto; padrão auto
output_format	enum	Não	png, jpeg ou webp; padrão webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Isso retorna imediatamente um taskId:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Depois, faça polling para obter o resultado:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Quando data.status for success, a imagem estará em data.output[0].url.Baixe-a imediatamente — essa URL tem expireAt e não serve para referência permanente como link externo.

Python

import time
import requests

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

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Padrões de produção

Polling e callbacks. O loop acima funciona bem para scripts e uso de baixo volume. Para qualquer cenário no servidor, prefira callback em vez de polling: adicione um objeto callback na mesma requisição —

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url deve ser HTTPS, e when: "final" (o único valor suportado atualmente) notifica você uma vez tanto em caso de sucesso quanto de falha — sem loop de polling, sem requisições desperdiçadas. A hiapi pode entregar o callback mais de uma vez, então faça deduplicação pelo taskId do seu lado.

Idempotência. Adicione o cabeçalho Idempotency-Key no POST /v1/tasks (qualquer string de até 255 bytes, por exemplo um id de pedido). Se um timeout de rede fizer seu cliente repetir o mesmo envio, a plataforma devolve o taskId original (com o cabeçalho de resposta Idempotent-Replay: true) em vez de criar — e cobrar — uma segunda tarefa. A chave tem escopo na sua conta e expira após 24 horas; reutilizá-la com um corpo de requisição diferente retorna 422 IDEMPOTENCY_KEY_MISMATCH em vez de criar silenciosamente uma nova tarefa, então uma incompatibilidade é um sinal de que você deve revisar sua lógica de retry em vez de repetir cegamente.

Erros de autenticação. Uma API key malformada ou incorreta falha rapidamente, retornando 401 com o código de erro permission_denied, antes de qualquer criação de tarefa:

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

Se você vir isso, a correção quase sempre está na própria key (variável de ambiente escrita errado, key expirada, prefixo sk- faltando) — não no corpo da requisição. Trate como não repetível até corrigir a key.

Sobre quality. O quality padrão é medium, que é um valor de lançamento razoável — aumentá-lo eleva tanto o custo quanto o tempo de geração, então só suba para high/xhigh/max depois de confirmar nos seus próprios testes que um dado prompt ainda tem sucesso confiável nesse nível.

Páginas relacionadas

• Página do modelo gpt-image-2.5-sunburst — capacidades da família do modelo, saídas de exemplo e todos os modos disponíveis.
• Documentação da API assíncrona unificada — o contrato completo de /v1/tasks compartilhado por todos os modelos de geração da hiapi (idempotência, callbacks, códigos de status).
• Documentação de autenticação — como criar e gerenciar API keys.
• Guia da API gpt-image-2.5-sunburst — se você quer o modo base (sem @pro), este guia detalha seu schema independente baseado em resolution.
• Preços — custo atual por imagem em cada faixa de quality.

FAQ

gpt-image-2.5-sunburst@pro e gpt-image-2.5-sunburst são modelos diferentes? É a mesma família de modelos, com rotas diferentes. O id puro gpt-image-2.5-sunburst (e seu modo /text-to-image) aceita um campo resolution (1K/2K/4K) e não tem os campos quality ou image_urls. O @pro substitui isso por faixas de quality e adiciona image_urls opcional, então use esta rota quando quiser controlar a faixa de qualidade ou fazer imagem-a-imagem na mesma chamada.

Preciso de imagens de referência? Não. Para texto-a-imagem, omita totalmente image_urls. Incluir de 1 a 16 URLs públicas de imagem passa a condicionar a saída às imagens de referência.

Posso usar este modelo sem API key? Não — toda requisição exige um cabeçalho Authorization: Bearer válido com uma API key hiapi real da sua conta. Não existe faixa não autenticada ou sem key.

Quanto custa? O preço varia conforme a faixa de quality e é mantido atualizado na página de preços, em vez de ser repetido aqui — consulte-a antes de estimar custos em escala.

E se meu callback nunca chegar? A entrega de callback não tem garantia de ser imediata, e a hiapi pode tentar reenviar (então faça deduplicação pelo taskId). Se você precisa de um limite rígido, mantenha um polling de fallback em GET /v1/tasks/:id após o timeout, em vez de esperar indefinidamente pelo callback.

Por que recebi um status fail em vez de um erro no envio? O envio (que retorna 200/taskId) só significa que a requisição foi aceita — a geração em si ainda pode falhar de forma assíncrona. Verifique data.status após o polling ou via callback, e consulte data.error para saber o motivo antes de reenviar.