Como usar o modo imagem-para-imagem do gpt-image-2 pela API do hiapi

Esta receita demonstra passo a passo como chamar o modo imagem-para-imagem do gpt-image-2 pela API unificada de tarefas do hiapi. Você vai obter um exemplo de curl pronto para executar, um script Python que pode ser embutido diretamente no backend, uma versão Node.js adequada para cenários serverless e, principalmente, os parâmetros que realmente importam e os detalhes que costumam causar problemas em produção.

Ao final da leitura, você terá um script que recebe a URL da imagem de referência e o prompt, e retorna a URL de uma imagem gerada, que você pode baixar diretamente ou entregar à sua camada de armazenamento.

Preparação

• Uma conta hiapi e uma chave de API. Obtenha-as no console do hiapi.
• Uma imagem de referência hospedada em uma URL HTTPS pública (ou um data URL base64 — ambos funcionam).
• Um prompt de texto descrevendo o que você quer que o modelo faça com essa imagem de referência.

É só isso. Não é necessário instalar nenhum SDK — o hiapi é HTTP + JSON, então qualquer linguagem capaz de enviar uma requisição POST serve.

Quer entender primeiro a geração puramente texto-para-imagem? Consulte Como gerar imagens com a API do hiapi. O padrão abaixo é o mesmo fluxo assíncrono de tarefas, apenas com um campo image a mais.

Chamada mínima funcional

O hiapi expõe todos os modelos de imagem pela mesma interface de tarefas assíncronas:

1. POST /v1/tasks — submete a tarefa e retorna um taskId.
2. Faça polling em GET /v1/tasks/{taskId} até status === "success", ou forneça callback.url para receber o resultado final via webhook.
3. Leia a URL da imagem em data.output[0].url e baixe ou armazene.

curl

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "input": {
      "prompt": "transform the subject into a watercolor painting, soft pastel palette",
      "image": "https://example.com/reference.jpg",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

A resposta retornada imediatamente traz o id da tarefa:

{ "data": { "taskId": "task_01HXXXX..." } }

Em seguida, consulte o resultado com polling:

curl https://api.hiapi.ai/v1/tasks/task_01HXXXX... \
  -H "Authorization: Bearer sk-YOUR_KEY"

Quando a tarefa estiver pronta, a resposta será assim:

{
  "data": {
    "status": "success",
    "output": [{ "url": "https://cdn.hiapi.ai/...png", "expireAt": "..." }]
  }
}

O output[0].url tem validade curta (observe o expireAt)