GPT Image 2 图生图

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

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

向 POST /v1/tasks 提交 model=gpt-image-2/image-to-image，即可使用 1–16 张参考图编辑图片。本页提供输入字段、线路差异、回调、轮询和代码示例。

请求参数

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/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}
''')

# 提交异步任务，成功立即返回 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/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

模型线路

默认线路：规范模型 ID 为 gpt-image-2/image-to-image，参考图字段为 input_urls，支持 1–16 张，价格随分辨率变化。

model string 必填

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

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

route string 可选

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

示例 default

input object 必填

业务参数对象；GPT Image 2 图生图的参考图片和生成配置都放在这里。

prompt string 必填

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

input_urls string[] 必填

参考图 URL 数组，最少 1 张，最多 16 张。支持 PNG、JPEG/JPG、WebP，不支持 SVG、GIF、BMP、TIFF；每张不超过 2,000 万像素且不超过 30 MB。必须是可公开访问、可直接下载的 http(s) 地址；也可以传 data URI。

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 不支持: 3:11:39:21

默认 1K 可选值: 1K2K4K

background enum 可选

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

可选值: autoopaquetransparent

callback object 可选

可选回调配置；生产环境建议传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务。

url string 必填

接收任务终态通知的 HTTPS 地址。

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

when enum 可选

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

默认 final 可选值: final

HiAPI ext 多比例 4K 线路解析后的规范模型 ID 为 gpt-image-2/image-to-image@ext：image_urls 支持 1–6 张，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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}
''')

# 提交异步任务，成功立即返回 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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

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

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

route string 必填

固定填 ext。

示例 ext

input object 必填

业务参数对象。

prompt string 必填

图像编辑指令，最长 20000 字符。

image_urls string[] 必填

参考图 URL 数组，最少 1 张，最多 6 张；数量参与 ext 线路动态计价。支持 PNG、JPEG/JPG、WebP，不支持 SVG、GIF 等其他格式；单张不超过 20 MB，建议不超过 2,000 万像素。必须是可公开访问、可直接下载的 http(s) 地址，也可以传 data URI。注意 ext 字段名是 image_urls，标准线路使用 input_urls。

aspect_ratio enum 可选

输出画幅比例；默认 auto 跟随输入图比例，显式指定则强制输出该比例。

默认 auto 可选值: 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 可选

可选回调配置；生产环境建议传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务。

url string 必填

接收任务终态通知的 HTTPS 地址。

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

when enum 可选

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

默认 final 可选值: final

请求示例

参考图产品化

把参考图改写成干净商品图。

请求体

{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}

生产请求带回调

生产环境推荐创建任务后等待 callback.url 收到终态通知。

请求体

{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}

成功响应

响应体

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

每次 1–16 张参考图，超过 16 张会在提交时返回 400（maxItems）。
支持 PNG、JPEG/JPG、WebP。SVG 在提交时返回 400；GIF、BMP、TIFF 等其他格式会导致任务失败。动图 WebP 只会使用首帧，不建议使用。
每张参考图不超过 2,000 万像素（约 4472×4472），文件不超过 30 MB；限制按单张计算，没有请求级合计限制。
URL 必须是可公开访问、可直接下载的 http 或 https 地址，不支持需要登录或有防盗链的地址；data URI 可以传。404、返回 HTML 页面或文件损坏不会同步报错，而是在任务阶段返回 status=fail。
ext 线路使用 image_urls，每次 1–6 张，格式要求相同，单张不超过 20 MB、建议不超过 2,000 万像素。

获取结果

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