Как использовать gpt-image-2.5-flare через hiapi API

gpt-image-2.5-flare — это единая модель на hiapi, которая обрабатывает как генерацию изображений по тексту, так и редактирование изображений через одну и ту же унифицированную конечную точку — вам не нужно использовать отдельные идентификаторы моделей для «генерации» и «редактирования». Это руководство проведёт вас от нуля до рабочего изображения за несколько минут с использованием асинхронного API задач hiapi, включая полный пример на Node.js и шаблоны производственного уровня (обратные вызовы, идемпотентность, повторные попытки), которые понадобятся перед запуском в продакшн.

Что вам понадобится

• Ключ hiapi API. Зарегистрируйтесь и получите его в панели управления — ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer.
• Любой HTTP-клиент. Примеры ниже используют Node.js 18+ (встроенный fetch), но те же три вызова можно выполнить с помощью curl, Python или любого инструмента, способного отправлять JSON POST-запросы.

hiapi предоставляет gpt-image-2.5-flare через одно семейство асинхронных конечных точек: вы отправляете задачу, затем опрашиваете результат или получаете webhook-обратный вызов по завершении задачи. Синхронного вызова «дождаться изображения в теле ответа» нет — генерация занимает несколько секунд, поэтому 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 изображений) и опишите в prompt, что делать с каждым изображением — та же модель, та же конечная точка, без отдельного идентификатора модели «редактирования»:

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).

Шаблоны производственного уровня

В продакшне используйте обратные вызовы вместо опроса. Опрос подходит для скриптов, но для настоящего бэкенда зарегистрируйте webhook, чтобы hiapi уведомлял вас в момент завершения задачи, а не вы периодически повторяли запросы GET /v1/tasks/<id>:

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

Ваш обработчик webhook получит тот же объект задачи, что и при опросе 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 — актуальные цены и playground, где можно опробовать prompt онлайн, чтобы протестировать перед интеграцией в код.
• Документация асинхронного API задач: создание задачи и получение статуса задачи — полный справочник полей для всех моделей (не только этой).
• Документация по аутентификации — как работают API-ключи и заголовок Authorization во всех конечных точках hiapi.
• Нужно перенести существующий код с gpt-image-2 или хотите учебник по редактированию, специфичный для Sunburst? См. руководство по API GPT Image 2.5 для пути миграции.
• Цены — текущая стоимость за изображение по уровням качества (здесь не дублируется, так как она меняется).

Часто задаваемые вопросы

gpt-image-2.5-flare — это одна модель или две (генерация + редактирование)? Одна. Генерирует она или редактирует, полностью зависит от того, включаете ли вы input.image_urls — переключаться на отдельный идентификатор модели не нужно.

Почему изображение не появляется в ответе сразу? Все модели изображений hiapi асинхронны — POST /v1/tasks возвращает только taskId. Вам нужно опрашивать GET /v1/tasks/<id>, пока status не станет success, или зарегистрировать callback, чтобы получить фактический массив output.

Сколько времени занимает задача? Обычно несколько секунд, иногда дольше при высокой нагрузке. Используйте щедрый таймаут опроса (60–120 секунд), а не предполагайте, что она всегда завершится мгновенно.

Можно ли передать несколько референсных изображений при редактировании? Да, image_urls принимает до 16 изображений — укажите в prompt роль каждого изображения (например, «используй позу с первого изображения и одежду со второго»), поскольку порядок массива важен.

Что произойдёт, если мой URL обратного вызова недоступен при завершении задачи? hiapi вызывает его один раз, когда задача достигает финального состояния (when: "final"). Если ваша конечная точка недоступна, вы не получите уведомление — для любых случаев, которые нельзя пропустить, используйте опрос как резервный вариант или периодически сверяйтесь с GET /v1/tasks/<id> по записанному ID задачи.

Нужно ли мне самостоятельно хранить URL вывода? Да — url в output[0] является временным и истекает. Скачайте или перезагрузите его в своё хранилище сразу после успешного завершения задачи.