Como usar gpt-image-2.5-flare@pro pela API hiapi: curl, Python e uma requisição executável

gpt-image-2.5-flare@pro é um dos modelos de imagem disponibilizados pela API de tarefas unificada da hiapi. Este guia começa demonstrando uma requisição mínima executável com curl e Python, e em seguida apresenta os parâmetros e padrões necessários para produção: callbacks, idempotência e tratamento de erros.

O que você precisa preparar

• Uma chave de API da hiapi. Você pode obtê-la no console da hiapi — cada chave começa com sk-.
• Use https://api.hiapi.ai como URL base. Toda requisição precisa do cabeçalho Authorization: Bearer sk-<your-key>.

A geração de imagens na hiapi (assim como todos os outros modelos assíncronos — vídeo, TTS, música) funciona pelo mesmo endpoint: POST /v1/tasks. Você primeiro cria uma tarefa e depois pode consultar periodicamente GET /v1/tasks/:id ou receber um callback quando a tarefa for concluída. Referência completa em: API assíncrona unificada.

Exemplo mínimo executável

curl

Crie a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

O que retorna aqui é um ID de tarefa, não a imagem — a geração de imagens é assíncrona:

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

Consulte o resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status muda na ordem queued → handling → archiving → success (ou fail). Quando o status é success, a imagem está em data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt é um timestamp Unix — baixe o arquivo ou hospede-o novamente antes que ele expire; depois disso, essa URL deixará de funcionar.

Python

import os
import time
import requests

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


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Instale a única dependência com pip install requests, exporte HIAPI_API_KEY e é só executar.

Parâmetros principais

gpt-image-2.5-flare oferece duas rotas: a rota padrão (usando diretamente o ID do modelo gpt-image-2.5-flare) e a rota pro (acrescentando @pro, como em todos os exemplos acima). Não existe sufixo explícito @default — passá-lo retorna MODEL_UNAVAILABLE.

input aceita os seguintes campos:

• prompt (string, obrigatório) — o único campo obrigatório.
• aspect_ratio — 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, ou dimensões explícitas em pixels como 1536x1024, 2048x2048, 3840x2160.
• quality — low, medium, high, xhigh, max ou auto.
• output_format — png, jpeg ou webp.
• background — auto, transparent ou opaque. Use transparent junto com output_format: png ou webp para obter material com fundo removido.

O schema é estrito — campos desconhecidos (size, n ou qualquer campo não listado) retornam 400 INVALID_REQUEST com additional properties '<field>' not allowed, em vez de serem ignorados silenciosamente. Se você precisa editar uma imagem existente em vez de gerar a partir de um prompt em branco, a hiapi oferece isso como um ID de modelo separado — consulte a página do modelo para a variante de imagem para imagem.

Padrões para produção

Use callbacks em vez de polling. Adicione um objeto callback na requisição de criação:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" é atualmente o único valor suportado — quando a tarefa atinge success ou fail, a hiapi envia uma única requisição POST para sua URL. O corpo do callback é exatamente o mesmo campo data retornado por GET /v1/tasks/:id.

Envie o cabeçalho Idempotency-Key. Se a requisição do seu lado expirar e você tentar novamente, a chave de idempotência impede que a hiapi crie (e cobre por) uma segunda tarefa para a mesma requisição.

Trate erros explicitamente. Uma chave inválida ou revogada retorna HTTP 401:

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

Um input malformado retorna HTTP 400, com error_code: "INVALID_REQUEST" e uma message indicando o campo problemático — verifique-a antes de tentar novamente; repetir um 400 com o mesmo corpo de requisição só vai falhar de novo.

Os preços de gpt-image-2.5-flare@pro (cobrados por imagem gerada com sucesso, conforme resolução e nível de qualidade) estão na página de preços.

Documentação relacionada

• Referência da API assíncrona unificada — ciclo de vida completo das tarefas, todos os tipos de modelo
• Criar tarefa — estrutura de requisição/resposta de POST /v1/tasks
• Obter detalhes da tarefa — polling de GET /v1/tasks/:id
• Autenticação — formato da chave de API e cabeçalhos
• Página do modelo gpt-image-2.5-flare@pro

Perguntas frequentes

Qual é a diferença entre a rota padrão e @pro? São duas rotas independentes da mesma família de modelos, selecionadas pelo ID de modelo que você envia (gpt-image-2.5-flare vs. gpt-image-2.5-flare@pro). Antes de escolher, consulte a página do modelo e a página de preços para entender as diferenças atuais de custo e capacidade.

Posso gerar PNGs transparentes? Sim — defina "background": "transparent" junto com "output_format": "png" (ou "webp").

Por que recebo additional properties 'size' not allowed? O schema é estrito. Use aspect_ratio (que também aceita dimensões explícitas em pixels como 1024x1024) em vez do campo size.

Quanto tempo a URL de saída é válida? Até o timestamp Unix expireAt no objeto output[0]. Baixe ou copie para o seu próprio armazenamento antes disso — a hiapi não continuará servindo esse arquivo depois.

Ainda preciso fazer polling se configurei um callback? Não, mas você ainda pode fazer polling — GET /v1/tasks/:id funciona normalmente com ou sem callback configurado, o que serve para verificação manual caso seu endpoint de callback perca uma entrega.

O que acontece se minha requisição incluir tanto input_urls quanto um prompt inválido? A validação é executada sobre todo o corpo da requisição antes de criar a tarefa — qualquer campo inválido (incluindo arrays de mídia malformados) retorna 400, e a tarefa não é criada (nem cobrada).