PixMind Docs
API 参考图片模型GPT Image 2.5 Sunburst

GPT Image 2.5 Sunburst 图片生成

使用 GPT Image 2.5 Sunburst 的质量与分辨率参数生成和编辑图片。

提供高可控图片生成与编辑,并可独立设置质量和分辨率。

提供方

OpenAI

模型 ID

gpt-image-2.5-sunburst

请求端点

POST /api-platform/v1/generations

鉴权与请求地址

API 地址为 https://aihub-admin.aimix.pro。创建和查询任务均须传入 Authorization: Bearer <PIXMIND_API_KEY>;提交 JSON 时还须设置 Content-Type: application/json。请将密钥保存在服务端环境变量中。

模型说明

  • 文生图时省略 referenceImages;编辑图片时传入参考图 URL。使用 resolution 设置输出分辨率档位,aspectRatio 设置画面比例。
  • quality 默认为 medium,resolution 默认为 1K,aspectRatio 默认为 1:1,sampleCount 默认为 1。

请求参数

参数类型必填说明
modelstring是

稳定的 PixMind 模型 ID,请使用 `gpt-image-2.5-sunburst`。

可选值: gpt-image-2.5-sunburst

promptstring是

用于生成或编辑的自然语言指令。

qualitystring否

生成质量档位。

可选值: low, medium, high, xhigh, max, auto

默认值: medium

resolutionstring否

输出分辨率档位。

可选值: 1K, 2K, 4K

默认值: 1K

aspectRatiostring否

期望输出画面比例。

可选值: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 9:21, 2:1, 1:2

默认值: 1:1

sampleCountinteger否

每个任务的输出图片张数,范围为 1–4。

可选值: 1, 2, 3, 4

默认值: 1

referenceImagesstring[] (URI)否

最多 16 张参考图,支持 JPEG、PNG、WebP,每张不超过 10 MB。URL 须能被服务端访问;文生图时省略。

请求示例

cURL
curl --request POST 'https://aihub-admin.aimix.pro/api-platform/v1/generations' \
  -H "Authorization: Bearer $PIXMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Create a skincare product campaign image on a warm beige background",
  "quality": "medium",
  "resolution": "1K",
  "aspectRatio": "1:1",
  "sampleCount": 1
}'
JavaScript
// Node.js 20+. Keep the API key on your server.
const apiKey = process.env.PIXMIND_API_KEY;
if (!apiKey) throw new Error("PIXMIND_API_KEY is required");

const response = await fetch("https://aihub-admin.aimix.pro/api-platform/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Create a skincare product campaign image on a warm beige background",
  "quality": "medium",
  "resolution": "1K",
  "aspectRatio": "1:1",
  "sampleCount": 1
}),
  signal: AbortSignal.timeout(30_000)
});

const task = await response.json();
if (!response.ok || task.code !== 1000) {
  throw new Error(task.message ?? task.error?.message ?? `HTTP ${response.status}`);
}
console.log(task);

任务受理响应

生成任务为异步处理。请保存 taskId,并轮询 GET /api-platform/v1/tasks/{taskId},直到状态为 ready 或 failed。

200 OK
{
  "code": 1000,
  "data": {
    "id": "img_44160",
    "taskId": 44160,
    "type": "image",
    "model": "gpt-image-2.5-sunburst",
    "status": "processing"
  }
}

查询任务与获取结果

将示例中的 44160 替换为受理响应中的 data.taskId,并使用同一用户所属的 Key 查询。pending、processing 为进行中状态;ready、failed 为终态。ready 时读取图片的 images 或视频的 videoUrl,failed 时读取 errorMessage。示例最多查询 60 次;超时后请保留 taskId 稍后继续查询,避免重复创建任务。结果 URL 仅为示意。

cURL
curl 'https://aihub-admin.aimix.pro/api-platform/v1/tasks/44160' \
  -H "Authorization: Bearer $PIXMIND_API_KEY"
JavaScript
// Continue after the request example above.
const taskId = task.data?.taskId;
if (!Number.isInteger(taskId)) throw new Error("Missing numeric taskId");

async function waitForTask(taskId) {
  for (let attempt = 0; attempt < 60; attempt++) {
    await new Promise(resolve => setTimeout(resolve, Math.min(2000 * 1.5 ** attempt, 10000)));
    const response = await fetch(`https://aihub-admin.aimix.pro/api-platform/v1/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(30_000)
    });
    const result = await response.json();
    if (!response.ok || result.code !== 1000) {
      throw new Error(result.message ?? `HTTP ${response.status}`);
    }
    const data = result.data;
    if (data.status === "ready") return data;
    if (data.status === "failed") {
      throw new Error(data.errorMessage ?? "Generation failed");
    }
    if (!["pending", "processing"].includes(data.status)) {
      throw new Error(`Unexpected task status: ${data.status}`);
    }
  }
  throw new Error(`Polling timed out; save taskId ${taskId} to query again later`);
}

const result = await waitForTask(taskId);
console.log(result.images);
200 OK · ready
{
  "code": 1000,
  "data": {
    "taskId": 44160,
    "type": "image",
    "model": "gpt-image-2.5-sunburst",
    "status": "ready",
    "progress": 100,
    "images": [
      "https://example.com/result.png"
    ]
  }
}

编辑已有图片

在请求中添加 referenceImages,并在 prompt 中描述需要保留和修改的内容。将以下示例 URL 替换为可访问的实际图片地址;不要传本地文件路径。

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "保留包装和品牌文字,将背景替换为暖米色摄影棚场景",
  "quality": "medium",
  "resolution": "1K",
  "aspectRatio": "1:1",
  "sampleCount": 1,
  "referenceImages": ["https://example.com/package.png"]
}

本地素材可先按临时媒体上传上传,再使用返回的 URL 创建任务。请求参数使用 camelCase;分辨率请传 resolution,例如 2K。

错误处理与重试

成功受理同时要求 HTTP 请求成功和业务字段 code: 1000;受理成功并不表示生成完成。生成失败时,任务查询返回 status: "failed" 和 errorMessage。

  • 参数错误:核对模型 ID、枚举值、图片张数及参考图地址后再提交。
  • 鉴权错误:核对 Bearer Key 及其关联应用,参见 API 鉴权。
  • 限流或临时服务错误:降低请求频率,使用带随机抖动的指数退避;参见错误码与重试。
  • 请求超时:保留已取得的 taskId,继续查询。未取得 taskId 时先确认原任务是否受理,避免盲目重复提交。

任务完整流程见异步任务。

On this page