Como usar o gpt-image-2.5-flare através da API hiapi

gpt-image-2.5-flare é um único modelo no hiapi que lida com geração de imagens a partir de texto e edição de imagens através do mesmo endpoint unificado — você não precisa usar IDs de modelo separados para "geração" e "edição". Este guia leva você do zero a uma imagem utilizável em poucos minutos usando a API de tarefas assíncronas do hiapi, com um exemplo completo em Node.js e os padrões de nível de produção que você precisará antes de ir ao ar (callbacks, idempotência, retentativas).

O que você precisa

• Uma chave de API do hiapi. Cadastre-se e obtenha uma no console — a chave tem o formato sk-... e vai no cabeçalho Authorization: Bearer.
• Qualquer cliente HTTP. Os exemplos abaixo usam Node.js 18+ (fetch nativo), mas as mesmas três chamadas podem ser feitas com curl, Python ou qualquer ferramenta capaz de enviar requisições JSON POST.

O hiapi expõe o gpt-image-2.5-flare através da mesma família de endpoints assíncronos: você envia uma tarefa e então consulta o resultado por polling, ou recebe um callback via webhook quando a tarefa é concluída. Não existe chamada síncrona de "esperar pela imagem no corpo da resposta" — a geração leva alguns segundos, então a API é baseada em tarefas desde o início.

Exemplo mínimo funcional (Node.js)

O código a seguir cria uma tarefa, faz polling até a conclusão e imprime a URL da imagem gerada.

const API_KEY = process.env.HIAPI_API_KEY; // sk-...
const BASE = "https://api.hiapi.ai/v1/tasks";

async function createTask(prompt) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      input: {
        prompt,
        aspect_ratio: "16:9",
        quality: "high",
      },
    }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`create task failed (${res.status}): ${JSON.stringify(err)}`);
  }
  const { data } = await res.json();
  return data.taskId; // e.g. "tk-hiapi-..."
}

async function waitForTask(taskId, { timeoutMs = 120_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/${taskId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    const { data: task } = await res.json();
    if (task.status === "success") return task;
    if (task.status === "fail") {
      throw new Error(`task failed: ${task.error?.code} ${task.error?.message}`);
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

const taskId = await createTask("a minimalist poster of a lighthouse at dawn, flat color");
const task = await waitForTask(taskId);
console.log(task.output[0].url); // baixe esta imagem — a URL expira, então salve-a prontamente

Execute com HIAPI_API_KEY=sk-... node generate.js. O array data.output na resposta só aparece quando status é "success"; cada entrada tem uma url temporária (com expireAt), então baixe ou reenvie imediatamente em vez de guardar o link.

Se você quiser editar uma imagem existente em vez de gerar do zero, adicione input.image_urls (um array de URLs publicamente acessíveis, 1–16 imagens) e descreva no prompt o que fazer com cada imagem — o mesmo modelo, o mesmo endpoint, sem necessidade de um ID de modelo de "edição" separado:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: {
    prompt: "replace the background with a studio gradient, keep the subject unchanged",
    image_urls: ["https://example.com/product-photo.jpg"],
  },
}),

Outros campos úteis de input: background (auto / transparent / opaque, padrão auto) e output_format (png / jpeg / webp, padrão webp). Este modelo não tem campo resolution — as dimensões são controladas inteiramente por aspect_ratio (se você precisar de dimensões exatas em pixels em vez de proporções, ele também aceita dimensões explícitas em pixels como 1536x1024).

Padrões de nível de produção

Use callbacks em vez de polling em produção. O polling é bom para scripts, mas para um backend real, registre um webhook para que o hiapi notifique você no momento em que a tarefa for concluída, em vez de você enviar repetidamente GET /v1/tasks/<id> em intervalos fixos:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: { prompt: "..." },
  callback: {
    url: "https://yourapp.com/webhooks/hiapi",
    when: "final", // o único valor suportado — dispara uma vez, em caso de sucesso ou falha
  },
}),

Seu handler de webhook recebe o mesmo objeto de tarefa que você obteria ao consultar GET /v1/tasks/<id> — verifique status e trate os casos success e fail separadamente.

Torne as retentativas idempotentes. Se seu executor de tarefas retentar chamadas HTTP falhas (timeouts, 5xx, instabilidade de rede) sem cuidado, você pode acabar enviando a mesma tarefa de geração duas vezes e pagando por ambas. Passe um cabeçalho Idempotency-Key estável — no máximo 255 bytes, normalmente seu próprio ID de tarefa/requisição — e requisições de retentativa com a mesma key retornarão a tarefa original em vez de criar uma nova:

headers: {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": jobId, // reuse o mesmo valor entre retentativas da mesma requisição lógica
},

Trate modos de falha específicos. Os seguintes códigos de status devem ser tratados com ramificações explícitas, em vez de tratar tudo como "retentar":

Código de status	Significado	Como tratar
401 com error.code: "permission_denied"	Chave de API incorreta ou ausente	Não retentar — verifique o cabeçalho Authorization
402	Saldo insuficiente	Não retentar — adicione créditos primeiro
400	Corpo da requisição inválido (campo errado, tipo errado)	Não retentar às cegas — corrija o corpo da requisição
503	Temporariamente indisponível	É seguro retentar com backoff
Tarefa com status: "fail"	A tarefa falhou após ser aceita (por exemplo, image_urls inacessível)	Verifique error.code / error.message, não entre em loop infinito

O corpo de resposta de erro 401 é assim — todos os modelos do hiapi têm o mesmo formato, então vale a pena verificar isso uma vez em um handler de erros compartilhado:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Referência

• Página do modelo gpt-image-2.5-flare — preços em tempo real e um playground para testar prompts online, útil para testar antes de integrar o código.
• Documentação da API de tarefas assíncronas: criar tarefa e obter status da tarefa — referência completa de campos para todos os modelos (não apenas este).
• Documentação de autenticação — como chaves de API e o cabeçalho Authorization funcionam em todos os endpoints do hiapi.
• Precisa migrar código existente de gpt-image-2, ou quer um tutorial de edição específico do Sunburst? Consulte o Guia da API GPT Image 2.5 para o caminho de migração.
• Preços — custo atual por imagem por faixa de qualidade (não copiado aqui, pois muda).

Perguntas frequentes

gpt-image-2.5-flare é um modelo ou dois (geração + edição)?Um. Se ele gera ou edita depende inteiramente de você incluir input.image_urls — não é necessário trocar para um ID de modelo separado.

Por que a imagem não aparece imediatamente na resposta?Os modelos de imagem do hiapi são todos assíncronos — POST /v1/tasks retorna apenas o taskId. Você precisa consultar GET /v1/tasks/<id> até que status seja success, ou registrar um callback para obter o array output real.

Quanto tempo leva uma tarefa?Normalmente um número de segundos de um dígito, ocasionalmente mais em períodos de alta carga. Use um timeout de polling generoso (60–120 segundos) em vez de assumir que sempre concluirá imediatamente.

Posso passar várias imagens de referência ao editar?Sim, image_urls aceita até 16 imagens — especifique no prompt o papel de cada imagem (por exemplo, "use a pose da primeira imagem com a roupa da segunda imagem"), pois a ordem do array importa.

O que acontece se minha URL de callback estiver inacessível quando a tarefa for concluída?O hiapi chama uma vez quando a tarefa atinge o estado final (when: "final"). Se seu endpoint estiver inacessível, você não receberá a notificação — para qualquer caso que não possa ser perdido, use o polling como fallback, ou reconcilie periodicamente com GET /v1/tasks/<id> usando o ID de tarefa que você registrou.

Preciso armazenar as URLs de saída por conta própria?Sim — a url em output[0] é temporária e expira. Baixe ou reenvie para seu próprio armazenamento imediatamente após a tarefa ser concluída com sucesso.