316 lines
7.3 KiB
Markdown
316 lines
7.3 KiB
Markdown
# GPT Image 2 示例文档
|
||
|
||
本文档基于用户站 `https://apicodex.xyz` 的接入方式整理，包含：
|
||
|
||
- 文生图示例
|
||
- 带参考图示例
|
||
- 支持的比例列表
|
||
- 实测返回结构
|
||
- 同步返回与异步轮询的兼容写法
|
||
|
||
## 接口地址
|
||
|
||
```text
|
||
POST https://apicodex.xyz/v1/images/generations
|
||
```
|
||
|
||
## 鉴权
|
||
|
||
请求头使用 Bearer Token：
|
||
|
||
```python
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
"Content-Type": "application/json",
|
||
}
|
||
```
|
||
|
||
## 支持的比例
|
||
|
||
当前整理到的 `size` 比例共有 13 种：
|
||
|
||
- `1:1`
|
||
- `16:9`
|
||
- `9:16`
|
||
- `4:3`
|
||
- `3:4`
|
||
- `3:2`
|
||
- `2:3`
|
||
- `5:4`
|
||
- `4:5`
|
||
- `2:1`
|
||
- `1:2`
|
||
- `21:9`
|
||
- `9:21`
|
||
|
||
说明：
|
||
|
||
- 上述 13 种比例按你提供的接口说明整理
|
||
- 本文档里实际请求验证过的是 `16:9`
|
||
|
||
建议只通过 `size` 传比例，不要在 `prompt` 里重复写比例。
|
||
|
||
## 文生图示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
url = "https://apicodex.xyz/v1/images/generations"
|
||
|
||
payload = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
|
||
"n": 1,
|
||
"size": "16:9",
|
||
}
|
||
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
"Content-Type": "application/json",
|
||
}
|
||
|
||
response = requests.post(url, json=payload, headers=headers, timeout=300)
|
||
print(response.json())
|
||
```
|
||
|
||
## 带参考图示例
|
||
|
||
注意：不要把参考图放进 `/v1/images/generations` 的 `image_urls` 字段。当前实测该字段会被忽略，返回 usage 中 `input_tokens_details.image_tokens` 仍为 `0`。带图请求应走：
|
||
|
||
```text
|
||
POST https://apicodex.xyz/v1/images/edits
|
||
```
|
||
|
||
### 参考图为 URL
|
||
|
||
```python
|
||
import requests
|
||
|
||
image_url = "https://example.com/photo.jpg"
|
||
image_resp = requests.get(image_url, timeout=60)
|
||
image_resp.raise_for_status()
|
||
|
||
url = "https://apicodex.xyz/v1/images/edits"
|
||
data = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "把这张照片变成水彩画风格",
|
||
"size": "1:1",
|
||
}
|
||
files = [
|
||
("image[]", ("photo.jpg", image_resp.content, image_resp.headers.get("Content-Type") or "image/jpeg")),
|
||
]
|
||
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
}
|
||
|
||
response = requests.post(url, data=data, files=files, headers=headers, timeout=300)
|
||
print(response.json())
|
||
```
|
||
|
||
### 参考图为 base64
|
||
|
||
```python
|
||
import requests
|
||
import base64
|
||
|
||
url = "https://apicodex.xyz/v1/images/edits"
|
||
|
||
data = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "把这张照片变成水彩画风格",
|
||
"size": "1:1",
|
||
}
|
||
image_bytes = base64.b64decode("iVBORw0KGgoAAAANSUhEUgAA...")
|
||
files = [
|
||
("image[]", ("reference.png", image_bytes, "image/png")),
|
||
]
|
||
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
}
|
||
|
||
response = requests.post(url, data=data, files=files, headers=headers, timeout=300)
|
||
print(response.json())
|
||
```
|
||
|
||
### 多张参考图
|
||
|
||
```python
|
||
import requests
|
||
|
||
url = "https://apicodex.xyz/v1/images/edits"
|
||
|
||
data = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "把这两张照片融合成一张海报",
|
||
"size": "4:3",
|
||
}
|
||
files = [
|
||
("image[]", ("photo-a.jpg", open("photo-a.jpg", "rb"), "image/jpeg")),
|
||
("image[]", ("photo-b.png", open("photo-b.png", "rb"), "image/png")),
|
||
]
|
||
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
}
|
||
|
||
try:
|
||
response = requests.post(url, data=data, files=files, headers=headers, timeout=300)
|
||
print(response.json())
|
||
finally:
|
||
for _, file_tuple in files:
|
||
file_tuple[1].close()
|
||
```
|
||
|
||
## 实测结果
|
||
|
||
本仓库在 `2026-04-22`（America/Los_Angeles）对以下请求做了真实测试：
|
||
|
||
```json
|
||
{
|
||
"model": "gpt-image-2",
|
||
"prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
|
||
"n": 1,
|
||
"size": "16:9"
|
||
}
|
||
```
|
||
|
||
实测结论：
|
||
|
||
- 请求返回 `HTTP 200`
|
||
- `size: "16:9"` 被接口接受
|
||
- 当前实测返回是“同步结果”，不是 `task_id`
|
||
- 顶层字段为 `created` 和 `data`
|
||
- `data[0]` 中包含 `b64_json` 和 `revised_prompt`
|
||
- 本次实测的 `revised_prompt` 为 `黄昏里的橘猫窗台景`
|
||
- 本次解码后的样例图尺寸为 `1196x1315`，没有严格匹配 `16:9`
|
||
|
||
实测返回结构可概括为：
|
||
|
||
```json
|
||
{
|
||
"created": 1776919131,
|
||
"data": [
|
||
{
|
||
"b64_json": "<base64 image data>",
|
||
"revised_prompt": "黄昏里的橘猫窗台景"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
本次测试产物已保存到仓库临时目录：
|
||
|
||
- `tmp/imagegen/gpt-image-2-16-9-response.json`
|
||
- `tmp/imagegen/gpt-image-2-16-9-sample.png`
|
||
|
||
## 同步返回时的取图方式
|
||
|
||
如果接口直接返回 `b64_json`，可以这样保存图片：
|
||
|
||
```python
|
||
import base64
|
||
import requests
|
||
|
||
url = "https://apicodex.xyz/v1/images/generations"
|
||
|
||
payload = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
|
||
"n": 1,
|
||
"size": "16:9",
|
||
}
|
||
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
"Content-Type": "application/json",
|
||
}
|
||
|
||
response = requests.post(url, json=payload, headers=headers, timeout=300)
|
||
data = response.json()
|
||
|
||
img_b64 = data["data"][0]["b64_json"]
|
||
with open("output.png", "wb") as f:
|
||
f.write(base64.b64decode(img_b64))
|
||
```
|
||
|
||
## 异步轮询写法
|
||
|
||
你提供的说明里写的是“提交后返回 `task_id`，再轮询 `/v1/tasks/{task_id}`”。如果后续该上游切回异步模式，可以用下面这种兼容写法：
|
||
|
||
```python
|
||
import base64
|
||
import time
|
||
import requests
|
||
|
||
url = "https://apicodex.xyz/v1/images/generations"
|
||
headers = {
|
||
"Authorization": "Bearer <token>",
|
||
"Content-Type": "application/json",
|
||
}
|
||
payload = {
|
||
"model": "gpt-image-2",
|
||
"prompt": "a corgi astronaut on the moon, cinematic, 8k",
|
||
"size": "16:9",
|
||
"n": 1,
|
||
}
|
||
|
||
resp = requests.post(url, json=payload, headers=headers, timeout=300)
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
|
||
# 情况 1：直接同步返回 base64
|
||
if isinstance(data, dict) and data.get("data") and data["data"][0].get("b64_json"):
|
||
with open("output.png", "wb") as f:
|
||
f.write(base64.b64decode(data["data"][0]["b64_json"]))
|
||
print("saved output.png")
|
||
|
||
# 情况 2：返回 task_id，需要轮询
|
||
elif isinstance(data, dict) and data.get("data", {}).get("id"):
|
||
task_id = data["data"]["id"]
|
||
task_url = f"https://apicodex.xyz/v1/tasks/{task_id}"
|
||
|
||
time.sleep(10)
|
||
while True:
|
||
task_resp = requests.get(task_url, headers=headers, timeout=60)
|
||
task_resp.raise_for_status()
|
||
task = task_resp.json()
|
||
|
||
status = task["data"]["status"]
|
||
if status == "completed":
|
||
print(task["data"]["result"]["images"][0]["url"][0])
|
||
break
|
||
if status == "failed":
|
||
raise RuntimeError(task["data"]["error"]["message"])
|
||
|
||
time.sleep(5)
|
||
|
||
else:
|
||
raise RuntimeError(f"unexpected response: {data}")
|
||
```
|
||
|
||
## 如果是异步结果，取图字段
|
||
|
||
如果接口返回的是任务模式，则最终图片 URL 取值为：
|
||
|
||
```text
|
||
data.result.images[0].url[0]
|
||
```
|
||
|
||
任务状态说明：
|
||
|
||
- `pending`: 已提交或排队中
|
||
- `processing`: 上游处理中
|
||
- `completed`: 成功
|
||
- `failed`: 失败
|
||
|
||
## 注意事项
|
||
|
||
- 单张图接口耗时可能较长，建议客户端超时至少设到 `300s`
|
||
- 本次实测中，`size: "16:9"` 虽然被接口接受，但返回图片尺寸并未严格命中 `16:9`；如果你的业务依赖固定画幅，建议在下载后自行校验并按需裁切
|
||
- 如果使用异步模式，首次轮询建议在提交后等待 `10~20` 秒
|
||
- 轮询间隔建议 `3~5` 秒，不要毫秒级高频轮询
|
||
- 建议失败时做有限次重试，尤其是 TLS 或上游网络抖动场景
|
||
- 如果服务端返回的是 `b64_json`，说明当前是同步模式，不需要再调 `/v1/tasks/{task_id}`
|