GPT Image 2 异步图片接口

ReachAPI 提供 GPT Image 2 的任务式图片接口。需要任务状态查询、终态回调，以及从 data[].url 读取最终图片地址时，请使用本文档说明的异步接口。

异步接口使用公开调用码 gpt-image-2-async。该调用码仅用于 POST /v1/images/create。OpenAI Image API 兼容接口的 /v1/images/generations 和 /v1/images/edits 仍使用 gpt-image-2。

1. 接口概览

提交任务：POST https://direct.reachapi.ai/v1/images/create
查询任务：GET https://direct.reachapi.ai/v1/tasks/{task_id}
调用码：gpt-image-2-async
执行方式：异步任务
结果字段：data[].url

请求头：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

2. 提交任务

请求体：

{
  "model": "gpt-image-2-async",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A children's book drawing of a veterinarian using a stethoscope to listen to a small animal.",
    "resolution": "1k",
    "aspect_ratio": "2:3",
    "quality": "medium",
    "background": "auto",
    "moderation": "auto",
    "output_format": "png"
  }
}

2.1 顶层参数

字段	类型	必填	说明
`model`	string	是	固定传 `gpt-image-2-async`
`callback_url`	string	否	任务终态回调地址。仅支持 `https`，最大长度 `2048`，本地、内网及私网目标会被拒绝
`input`	object	是	图片生成参数

2.2 `input` 参数

字段	类型	必填	说明
`prompt`	string	是	文生图或图像编辑提示词
`image_urls`	`array<string>`	否	参考图 URL 列表。不传或传空数组表示文生图，非空表示图像编辑，最多 14 张
`size`	string	否	精确输出尺寸，例如 `1024x1536`。如传入，则优先于 `resolution + aspect_ratio`
`resolution`	string	否	标准分辨率档位。可选值：`1k`、`2k`、`4k`。不传时默认 `1k`
`aspect_ratio`	string	否	标准画面比例。可选值：`1:1`、`3:2`、`2:3`。不传时默认 `1:1`
`quality`	string	否	质量档位。可选值：`low`、`medium`、`high`。不传时默认 `medium`
`background`	string	否	背景模式。可选值：`auto`、`opaque`、`transparent`。`gpt-image-2` 不支持 `transparent`
`moderation`	string	否	审核模式。可选值：`auto`、`low`
`output_format`	string	否	输出格式偏好。可选值：`png`、`jpeg`、`webp`

说明：

input.size 优先于 resolution + aspect_ratio
input.size 的最长边必须小于或等于 3840px，两条边都必须是 16px 的倍数，长边与短边比例不能超过 3:1，总像素数必须不少于 655,360 且不超过 8,294,400
background=transparent 不能与 output_format=jpeg 同时使用
如果需要使用本地图片，请先上传为可访问的 HTTPS URL，再传入 input.image_urls

2.3 标准尺寸映射

`resolution + aspect_ratio`	输出尺寸
`1k + 1:1`	`1024x1024`
`1k + 3:2`	`1536x1024`
`1k + 2:3`	`1024x1536`
`2k + 1:1`	`2048x2048`
`2k + 3:2`	`2048x1152`
`4k + 3:2`	`3840x2160`
`4k + 2:3`	`2160x3840`

如果组合不在表格内，请使用 input.size 指定精确输出尺寸。

3. 计费规则

异步任务接口按本次请求归一后的 resolution + quality 固定按次计费。

quality 大小写不敏感，会归一为 low、medium、high；不传时默认 medium。

`quality`	`1k`	`2k`	`4k`
`low`	`$0.010`	`$0.020`	`$0.030`
`medium`	`$0.060`	`$0.120`	`$0.180`
`high`	`$0.220`	`$0.440`	`$0.660`

计费用的分辨率按以下方式确定：

如果传入 input.size，会按宽高像素数映射为 1k、2k 或 4k
如果未传 input.size，使用 input.resolution；未传时默认 1k

4. 请求示例

4.1 文生图

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "An editorial fashion photo of a silver handbag on a reflective pedestal, soft studio lighting",
      "resolution": "4k",
      "aspect_ratio": "2:3",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.2 自定义尺寸

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "A fashion poster with a tall custom composition",
      "size": "2336x3504",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.3 图像编辑

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "Turn this sneaker photo into a premium e-commerce hero shot with a clean studio background",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "jpeg"
    }
  }'

5. 提交响应

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

字段	类型	说明
`code`	integer	平台业务状态码
`msg`	string	状态或错误信息
`status`	string	初始任务状态，通常为 `queued`
`task_id`	string	任务 ID，后续用于查询结果
`data`	array	提交阶段为空数组

6. 查询任务

请求：

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

状态说明：

状态	说明
`queued`	已受理，等待执行
`generating`	生成中
`success`	生成成功
`failed`	生成失败

成功响应：

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/gpt-image-2.png",
      "size": "1024x1536",
      "revised_prompt": "A children's book illustration of a veterinarian using a stethoscope."
    }
  ],
  "cost": {
    "spend": 0.12
  }
}

失败响应：

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

7. 回调说明

如果提交任务时传了 callback_url，ReachAPI 会在任务进入 success 或 failed 后向该地址发送 POST 请求。回调 body 与任务查询接口的响应结构一致。

回调约束：

仅支持 HTTPS 地址
最大长度 2048
localhost、.local、私网和本地 IP 目标会被拒绝
单次投递超时 10s
失败后最多重试 2 次，总计最多投递 3 次

8. 参数约束

prompt 必填，且不能为空字符串
image_urls 仅支持服务端可访问的 HTTPS URL
image_urls 最多 14 张
不支持 image_base64s
不支持 n > 1
此异步接口不支持 mask
不支持 output_compression
不支持 user
size 必须使用像素尺寸，最长边不超过 3840px，两条边都是 16px 的倍数，长边与短边比例不超过 3:1，总像素数介于 655,360 到 8,294,400 之间
resolution 支持 1k、2k、4k
标准映射模式下，aspect_ratio 支持 1:1、3:2、2:3
若未传 size，则 resolution + aspect_ratio 必须命中标准尺寸映射表
quality 支持 low、medium、high
background、moderation、output_format 需要按文档枚举值传入
background=transparent 不支持 output_format=jpeg

GPT Image 2 异步图片接口

On this page