Como usar gpt-image-2-beta pela API da hiapi: parâmetros, código e exemplos executáveis

gpt-image-2-beta é a rota mínima e de preço fixo para acessar o GPT Image 2 na hiapi: dois campos de entrada, um preço, sem ajustes de proporção ou qualidade. Este guia mostra o exemplo mínimo executável, a estrutura exata de parâmetros (confirmada por sondagem do endpoint em produção) e como ela se compara à rota padrão gpt-image-2/text-to-image, para que você possa decidir quando usar cada uma.

Pré-requisitos

Você precisa obter uma chave de API na página de API Keys do painel da hiapi — a chave começa com sk-. O preço atual por imagem está na página do modelo gpt-image-2-beta e na página de preços.

Como todos os modelos de imagem da hiapi, este modelo roda no endpoint unificado de tarefas assíncronas:

• POST https://api.hiapi.ai/v1/tasks — cria uma tarefa de geração
• GET https://api.hiapi.ai/v1/tasks/{taskId} — consulta o status da tarefa

O que a rota beta tem de diferente

gpt-image-2/text-to-image (a rota padrão) aceita aspect_ratio + resolution e cobra por faixa de resolução (US$ 0,03 para 1K, até US$ 0,06 para 4K). gpt-image-2-beta reduz tudo isso a um preço fixo unificado de US$ 0,02 por imagem e um campo size opcional — uma string de dimensões em pixels literais, como "1024x1024" ou "1600x900", não uma proporção. Se size for totalmente omitido, o modelo recorre ao seu próprio tamanho de saída padrão.

O custo é: você abre mão do controle refinado de proporção/resolução em troca de um preço menor e mais simples. É adequado quando você só precisa "gerar uma imagem barata" sem se importar com a composição exata.

Exemplo mínimo executável (curl)

# 1. Create the task
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-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

A imagem concluída fica em data.output[0].url. Essa URL tem um expireAt curto — baixe-a imediatamente e re-hospede-a no seu próprio armazenamento; não a vincule diretamente em conteúdo de produção.

Imagem de exemplo gerada pela chamada curl acima (com um prompt diferente), usando size: "1024x1024".

Python: criar + consultar + salvar em disco

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Referência de parâmetros

O objeto input de gpt-image-2-beta aceita apenas dois campos — a estrutura é additionalProperties: false, portanto qualquer outro conteúdo é rejeitado diretamente, em vez de ser ignorado silenciosamente.

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Descrição textual da imagem a ser gerada.
size	string	Não	Dimensões em pixels literais, por exemplo "1024x1024", "1600x900". Não é uma palavra-chave de proporção. Se omitido, usa o tamanho de saída padrão do modelo.

O que não é suportado (e os erros que você receberá)

A estrutura beta não aceita nenhum campo usado pela rota padrão gpt-image-2/text-to-image ou pela OpenAI Images API — aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user ou style. Enviar qualquer um deles retorna imediatamente HTTP 400, por exemplo:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

Se você está migrando código da rota padrão ou da Images API da OpenAI, primeiro reduza-o a prompt + size e então aponte para gpt-image-2-beta.

Preços: beta vs padrão vs @ext

Rota	Preço	Controles
gpt-image-2-beta	US$ 0,02/imagem fixo	Apenas size (dimensões em pixels)
gpt-image-2/text-to-image (padrão)	US$ 0,03 (1K) / US$ 0,04 (2K) / US$ 0,06 (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	US$ 0,007–US$ 0,76, por qualidade × resolução	16 proporções, faixas de qualidade

Antes de definir a rota em produção, consulte a página de preços — os preços de qualquer modelo podem mudar.

Dicas para construir na rota beta

• Trate a lista de campos acima como o contrato atual, não como um contrato permanente. A estrutura ou o preço da rota beta têm mais chance de serem ajustados do que os da rota padrão — se você depende dela em produção, reconsulte a página do modelo periodicamente.
• Como size é opcional, se o seu layout depende de um tamanho específico, sempre o passe explicitamente — não conte com o valor padrão atual permanecendo inalterado.
• Trate status: "fail" como faria com qualquer outro modelo de imagem da hiapi: leia task.error.code / task.error.message e tente novamente com backoff, em vez de supor que toda falha é transitória.

Perguntas frequentes

gpt-image-2-beta e gpt-image-2/text-to-image são o mesmo modelo? Por baixo é o mesmo modelo GPT Image 2, mas a rota da API é diferente — a rota beta troca controles de parâmetros por um preço fixo e menor.

Posso solicitar uma proporção específica? Não diretamente. Escolha uma string de size com a proporção largura:altura que você precisa (por exemplo, "1600x900" para 16:9), em vez de usar a enumeração aspect_ratio.

O que acontece se eu não passar size de jeito nenhum? A tarefa ainda será concluída — o modelo usa seu próprio tamanho de saída padrão.

Leitura relacionada

Para a rota completa com controle explícito de proporção e resolução, consulte Como usar gpt-image-2/text-to-image pela API da hiapi. Pronto para experimentar? Obtenha uma chave na página de API Keys e execute o exemplo curl acima.