如何通过 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：你提交任务，然后轮询结果，或在任务完成时接收 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 中描述对每张图像的处理——同一个模型、同一个端点，无需单独的“编辑”模型 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 这样的显式像素尺寸）。

生产级模式

在生产环境中使用回调代替轮询。轮询适合脚本，但对于真正的后端，请注册 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——使用相同 key 的重试请求会返回原始任务，而不是创建新任务：

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 模型页面——实时定价和一个可在线试用 prompt 的 playground，方便在接入代码前测试。
• 异步任务 API 文档：创建任务和获取任务状态——所有模型（不仅是此模型）的完整字段参考。
• 认证文档——API 密钥和 Authorization 请求头在所有 hiapi 端点中的工作方式。
• 需要从 gpt-image-2 迁移现有代码，或想要 Sunburst 专属的编辑教程？请参阅 GPT Image 2.5 API 指南了解迁移路径。
• 定价——当前按质量档位划分的每图像成本（此处不复制，因为它会变化）。

常见问题

gpt-image-2.5-flare 是一个模型还是两个（生成 + 编辑）？一个。它生成还是编辑完全取决于你是否包含 input.image_urls——无需切换到单独的模型 ID。

为什么响应里没有立即出现图像？hiapi 的图像模型全部是异步的——POST /v1/tasks 只返回 taskId。你需要轮询 GET /v1/tasks/<id> 直到 status 为 success，或注册 callback 才能获取实际的 output 数组。

任务需要多长时间？通常为个位数秒，负载高时偶尔会更长。使用宽松的轮询超时（60–120秒），而不是假设它总能立即完成。

编辑时可以传入多张参考图像吗？可以，image_urls 最多接受 16 张图像——在 prompt 中说明每张图像的作用（例如“使用第一张图像的姿势，搭配第二张图像的服装”），因为数组顺序很重要。

如果任务完成时我的回调 URL 无法访问会怎样？hiapi 在任务达到最终状态时调用一次（when: "final"）。如果你的端点无法访问，你不会收到通知——对于任何不能遗漏的情况，请将轮询作为后备方案，或使用你记录的任务 ID 定期与 GET /v1/tasks/<id> 对账。

我需要自己存储输出 URL 吗？是的——output[0] 中的 url 是临时的并且会过期。任务成功后请立即下载或重新上传到你自己的存储。