GPT Image 2 API

POST Base URL: https://api.hiapi.ai /v1/tasks

提交文生图或图生图任务，使用 GET /v1/tasks/:id 查询结果。

向 POST /v1/tasks 提交 model=gpt-image-2/text-to-image 即可调用 GPT Image 2。本页提供完整参数、线路差异、回调、轮询和代码示例。

请求参数

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

模型线路

默认线路：规范模型 ID 为 gpt-image-2/text-to-image，支持 1K/2K/4K 和 16 种画幅（含 auto），价格随分辨率变化。

model string 必填

固定填 gpt-image-2/text-to-image。

示例 gpt-image-2/text-to-image

route string 可选

默认线路可不传，或显式传 default。

示例 default

input object 必填

业务参数对象；GPT Image 2 的模型专属配置都放在这里。

prompt string 必填

文本提示词，最多 20000 字符。

aspect_ratio enum 可选

生成图片的比例，默认 auto。

默认 auto 可选值: auto1:13:22:34:33:45:44:516:99:16 +6

resolution enum 可选

图片输出分辨率。

自动画幅: auto 或未指定画幅时，仅支持 1K
2K 不支持: 5:44:53:11:39:21
4K 不支持: 1:13:11:39:21

默认 1K 可选值: 1K2K4K

background enum 可选

background 参数仅支持 1K；使用 2K/4K 时请省略此参数。

可选值: autoopaquetransparent

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

beta 线路解析后的规范模型 ID 为 gpt-image-2/text-to-image@beta：用 size 字段替代 aspect_ratio 与 resolution。推荐传基础 model，并在顶层传 route: "beta"。

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2/text-to-image",
  "route": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gpt-image-2/text-to-image",
  "route": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2/text-to-image",
  "route": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 gpt-image-2/text-to-image，配合 route 选择 beta 线路。

示例 gpt-image-2/text-to-image

route string 必填

固定填 beta。

示例 beta

input object 必填

业务参数对象。

prompt string 必填

文本提示词，最多 20000 字符。

size string 可选

输出尺寸，替代 aspect_ratio 与 resolution；默认 auto，或传入小写 x 分隔的宽x高，宽高各为 3–5 位数字（例如 1024x1024）。

默认 auto 示例 1024x1024

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

HiAPI ext 多比例 4K 线路解析后的规范模型 ID 为 gpt-image-2/text-to-image@ext：全部 16 种画幅在 1K/2K/4K 三档都可用，resolution 与 quality 必填。推荐在顶层传 route: "ext"。

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "low"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "low"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "low"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 gpt-image-2/text-to-image，配合 route 选择 ext 线路。

示例 gpt-image-2/text-to-image

route string 必填

固定填 ext。

示例 ext

input object 必填

业务参数对象。

prompt string 必填

文本提示词，最多 20000 字符。

aspect_ratio enum 可选

输出画幅比例；全部 16 个比例在 1K/2K/4K 三档分辨率下都可用（含 5:4、4:5、2:1 等）。

默认 1:1 可选值: auto1:13:22:34:33:45:44:516:99:16 +6

resolution enum 必填

HiAPI ext 线路的分辨率档位：1K、2K 或 4K；实际像素尺寸随画幅比例变化。

默认 1K 可选值: 1K2K4K

quality enum 必填

质量档位，影响价格：low 干净锐利适合走量，medium 细节明显提升，high 电影级质感。

默认 low 可选值: lowmediumhigh

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

请求示例

基础文生图

最小可用请求，只传提示词、比例和分辨率。

请求体

{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

透明背景产品图

需要透明背景时传 background=transparent，并使用 1K 分辨率。

请求体

{
  "model": "gpt-image-2/text-to-image",
  "route": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}

方图产品素材

适合商品页、社媒头像、封面缩略图等方形投放位。

请求体

{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "low"
  }
}

成功响应

响应体

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-..."
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从 data.output[].url 下载图片，并在 expireAt 前保存。
如果 POST 同步返回 4xx，修正认证、余额或请求 schema；如果查询到 status=fail，记录 data.error 并不要盲目重试同一个无效请求。