hiapi API로 gpt-image-2.5-flare 사용하는 방법

gpt-image-2.5-flare는 hiapi의 단일 모델로, 동일한 통합 엔드포인트를 통해 텍스트-이미지 생성과 이미지 편집을 동시에 처리합니다. 즉, '생성'과 '편집'을 위해 별도의 모델 ID를 사용할 필요가 없습니다. 이 가이드는 hiapi의 비동기 작업 API를 사용하여 몇 분 만에 처음부터 사용 가능한 이미지를 생성하는 방법을 안내하며, 완전한 Node.js 예제와 출시 전에 필요한 프로덕션 수준의 패턴(콜백, 멱등성, 재시도)을 포함합니다.

준비 사항

• hiapi API 키. 콘솔에서 등록하고 발급받으세요. 키는 sk-... 형식이며 Authorization: Bearer 요청 헤더에 넣습니다.
• 모든 HTTP 클라이언트. 아래 예제는 Node.js 18+(내장 fetch)을 사용하지만, 동일한 세 번의 호출을 curl, Python 또는 JSON POST 요청을 보낼 수 있는 모든 도구로 수행할 수 있습니다.

hiapi는 동일한 비동기 엔드포인트 패밀리를 통해 gpt-image-2.5-flare를 제공합니다. 작업을 제출한 다음 결과를 폴링하거나, 작업 완료 시 웹훅 콜백을 받습니다. '응답 본문에서 이미지를 기다리는' 동기 호출은 없습니다. 생성에 수 초가 걸리므로 API는 처음부터 작업 기반으로 설계되었습니다.

최소 실행 예제(Node.js)

다음 코드는 작업을 생성하고, 완료될 때까지 폴링한 후, 생성된 이미지 URL을 출력합니다.

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); // download this — it expires, so save it promptly

HIAPI_API_KEY=sk-... node generate.js로 실행하세요. 응답의 data.output 배열은 status가 "success"일 때만 나타납니다. 각 항목에는 임시 url(expireAt 포함)이 있으므로 링크를 저장하지 말고 즉시 다운로드하거나 다시 업로드하세요.

처음부터 생성하는 대신 기존 이미지를 편집하려면 input.image_urls(공개 접근 가능한 URL 배열, 1–16장의 이미지)를 추가하고 프롬프트에서 각 이미지에 대한 처리를 설명하세요. 동일한 모델, 동일한 엔드포인트이며 별도의 '편집' 모델 ID가 필요하지 않습니다:

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"],
  },
}),

기타 유용한 input 필드: background(auto / transparent / opaque, 기본값 auto)와 output_format(png / jpeg / webp, 기본값 webp). 이 모델에는 resolution 필드가 없습니다. 크기는 전적으로 aspect_ratio로 제어됩니다(비율이 아닌 정확한 픽셀 크기가 필요한 경우 1536x1024와 같은 명시적 픽셀 크기도 허용합니다).

프로덕션 수준 패턴

프로덕션 환경에서는 폴링 대신 콜백을 사용하세요. 폴링은 스크립트에 적합하지만, 실제 백엔드에서는 GET /v1/tasks/<id>를 주기적으로 반복 요청하는 대신 웹훅을 등록하여 작업이 완료되는 순간 hiapi가 알려주도록 하세요:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: { prompt: "..." },
  callback: {
    url: "https://yourapp.com/webhooks/hiapi",
    when: "final", // the only supported value — fires once, on success or fail
  },
}),

웹훅 핸들러는 GET /v1/tasks/<id> 폴링과 동일한 작업 객체를 받습니다. status를 확인하고 success와 fail에 따라 분기 처리하세요.

재시도를 멱등하게 만드세요. 작업 실행기가 실패한 HTTP 호출(타임아웃, 5xx, 네트워크 불안정)을 부주의하게 재시도하면 동일한 생성 작업을 두 번 제출하고 두 번 과금될 수 있습니다. 안정적인 Idempotency-Key 요청 헤더(최대 255바이트, 일반적으로 자체 작업/요청 ID)를 전달하세요. 동일한 키를 사용한 재시도 요청은 새 작업을 생성하지 않고 원래 작업을 반환합니다:

headers: {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": jobId, // reuse the same value across retries of the same logical request
},

특정 실패 모드를 처리하세요. 다음 상태 코드는 모든 경우를 '재시도'로 처리하지 말고 명시적으로 분기 처리해야 합니다:

상태 코드	의미	처리 방식
401 및 error.code: "permission_denied"	API 키 오류 또는 누락	재시도하지 마세요. Authorization 헤더를 확인하세요
402	잔액 부족	재시도하지 마세요. 먼저 충전하세요
400	유효하지 않은 요청 본문(필드 오류, 타입 오류)	무작정 재시도하지 마세요. 요청 본문을 수정하세요
503	일시적 사용 불가	안전하게 백오프 후 재시도 가능
작업 status: "fail"	작업이 수락된 후 실패(예: image_urls에 접근 불가)	error.code / error.message를 확인하고 무한 루프에 빠지지 마세요

401 오류 응답 본문은 다음과 같습니다. 모든 hiapi 모델의 형태가 동일하므로 공유 오류 핸들러에서 한 번만 검사하면 됩니다:

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

참고 자료

• gpt-image-2.5-flare 모델 페이지 — 실시간 가격과 코드에 통합하기 전에 프롬프트를 온라인으로 테스트할 수 있는 플레이그라운드.
• 비동기 작업 API 문서: 작업 생성 및 작업 상태 조회 — 모든 모델(이 모델뿐만 아니라)의 전체 필드 참조.
• 인증 문서 — 모든 hiapi 엔드포인트에서 API 키와 Authorization 헤더가 작동하는 방식.
• gpt-image-2에서 기존 코드를 마이그레이션해야 하거나 Sunburst 전용 편집 튜토리얼을 원하시나요? 마이그레이션 경로는 GPT Image 2.5 API 가이드를 참조하세요.
• 가격 — 현재 품질 등급별 이미지당 비용(변동되므로 여기에 복사하지 않음).

자주 묻는 질문

gpt-image-2.5-flare는 하나의 모델인가요, 두 개(생성 + 편집)인가요? 하나입니다. 생성인지 편집인지는 input.image_urls 포함 여부에 따라 완전히 결정됩니다. 별도의 모델 ID로 전환할 필요가 없습니다.

왜 응답에 이미지가 즉시 나타나지 않나요? hiapi의 이미지 모델은 모두 비동기입니다. POST /v1/tasks는 taskId만 반환합니다. 실제 output 배열을 얻으려면 status가 success가 될 때까지 GET /v1/tasks/<id>를 폴링하거나 callback을 등록해야 합니다.

작업에 얼마나 걸리나요? 일반적으로 한 자릿수 초이며, 부하가 높을 때는 가끔 더 오래 걸립니다. 항상 즉시 완료된다고 가정하지 말고 넉넉한 폴링 타임아웃(60–120초)을 사용하세요.

편집 시 여러 참조 이미지를 전달할 수 있나요? 네, image_urls는 최대 16장의 이미지를 허용합니다. 배열 순서가 중요하므로 프롬프트에서 각 이미지의 역할을 설명하세요(예: '첫 번째 이미지의 포즈를 사용하고 두 번째 이미지의 의상을 적용').

작업 완료 시 콜백 URL에 접근할 수 없다면 어떻게 되나요? hiapi는 작업이 최종 상태에 도달할 때 한 번 호출합니다(when: "final"). 엔드포인트에 접근할 수 없으면 알림을 받지 못합니다. 누락되면 안 되는 모든 경우에는 폴링을 대체 수단으로 사용하거나, 기록한 작업 ID로 GET /v1/tasks/<id>를 주기적으로 대조하세요.

출력 URL을 직접 저장해야 하나요? 네. output[0]의 url은 임시이며 만료됩니다. 작업 성공 후 즉시 다운로드하거나 자체 스토리지에 다시 업로드하세요.