Image2 接入文档
这份文档描述 `ai.cozesf.cc` 当前可用的 Image2 文生图与图生图接入方式。调用入口走本站统一网关，鉴权、调度和计费都在站内完成。
POST
/v1/images/generations
/v1/images/edits
1K / 2K / 4K
0.2 起 / 张
OpenAI 兼容
当前站内已经把 Image2 图片渠道接入到 `image2分组`。原有模型和新增的 `gpt-image-2.5`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 都通过标准图片接口调用；平台内部会兼容 xibapi 的异步任务格式。
兼容别名 `image2` 会保留在模型列表里。xibapi 的三个 Image2.5 模型已经加入路由，`gpt-image-2.5` 已通过本站标准图片接口实测返回 HTTP 200。
1. 当前站内接入规则
| 项目 | 当前规则 |
|---|---|
| 文生图地址 | https://ai.cozesf.cc/v1/images/generations |
| 图生图地址 | https://ai.cozesf.cc/v1/images/edits |
| Image2.5 兼容调用 | 仍使用 /v1/images/generations 或 /v1/images/edits；xibapi /v1/videos 仅在平台内部使用 |
| 认证方式 | Authorization: Bearer <你的站内 API Key> |
| 外部可用模型名 | gpt-image-2、gpt-image-2.5-1k、gpt-image-2-2K、gpt-image-2-4K、gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst；兼容别名 image2 |
| 站内实际转发渠道 | image2 |
| 当前推荐尺寸 | 本站统一使用 size；flare / sunburst 用像素尺寸选择 1K / 2K / 4K 档位 |
| 默认返回 | 建议显式传 response_format；传 url 读 data[0].url，传 b64_json 读 data[0].b64_json |
| 图生图图片字段 | JSON 传一个或多个 images[].image_url；本地文件上传多图时重复传多个 image 字段 |
| 当前不建议使用 | /v1/chat/completions 不作为站内标准生图入口；请使用图片原生接口 |
2. 接入步骤
- 在控制台创建或获取一个已经分配到 `image2分组` 的站内 API Key。
- 文生图使用 `https://ai.cozesf.cc/v1/images/generations`；图生图使用 `https://ai.cozesf.cc/v1/images/edits`。
- 1K 请求体可写 `gpt-image-2` 或 `gpt-image-2.5-1k`；2K 使用 `gpt-image-2-2K`；4K 使用 `gpt-image-2-4K`。
- 价格按规格计费：1K 0.2 / 张，2K 0.3 / 张，4K 0.5 / 张。
- Image2.5 模型也使用上述标准图片接口；平台内部等待上游异步任务完成，客户端不需要调用或轮询 `/v1/videos`。
- 图生图如果传图片 URL，正式公网入口的 JSON 写法使用 `images` 数组，里面放 `image_url`；如果传本地文件，表单字段名固定用 `image`。
- 建议显式传 `response_format`；传 `url` 读 `data[0].url`，传 `b64_json` 读 `data[0].b64_json`。
3. 文生图请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 1K 可传 gpt-image-2 或 gpt-image-2.5-1k；2K / 4K 分别传 gpt-image-2-2K、gpt-image-2-4K。 |
| prompt | string | 是 | 图片提示词。 |
| size | string | 否 | 1K 使用本文档列出的预设，例如 1024x1024、720x1280；2K / 4K 请按目标规格显式传尺寸，最终尺寸以上游返回为准。 |
| response_format | string | 否 | 可选。建议显式传 url 或 b64_json。 |
4. 图生图请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 1K 可传 gpt-image-2 或 gpt-image-2.5-1k；2K / 4K 分别传 gpt-image-2-2K、gpt-image-2-4K。 |
| prompt | string | 是 | 描述你希望如何改图。 |
| images | array<object> | JSON 时是 | 正式公网入口的 JSON 图生图写法。支持多张参考图，格式为 [{ "image_url": "https://..." }, ...]。 |
| image | file | Multipart 时是 | 本地文件上传时使用这个字段名；多张图片请重复传多个 image 字段，不要写成 image[]。 |
| size | string | 否 | 1K 使用本文档列出的预设；2K / 4K 请按目标规格显式传尺寸，最终尺寸以上游返回为准。 |
| response_format | string | 否 | 可选。建议显式传 url 或 b64_json。 |
5. 尺寸与模型档位
当前分组已开放 1K / 2K / 4K。1K 继续使用稳定预设；2K / 4K 通过模型名分流到高规格渠道，建议同时显式传 size，最终输出尺寸以上游返回字段为准。
| 规格 | 模型名 | 价格 | 说明 |
|---|---|---|---|
| 1K | gpt-image-2 | 0.2 / 张 | 常规文生图 / 图生图，推荐默认使用。 |
| 1K | gpt-image-2.5-1k | 0.2 / 张 | Image 2.5 的 1K 模型，适合需要更高质量的文生图 / 图生图。 |
| 1K | gpt-image-2.5 | 0.2 / 张 | Image2.5 新版标准档，仅支持 1K；通过标准图片接口调用。 |
| 1K / 2K / 4K | gpt-image-2.5-flare | 0.2 / 0.3 / 0.5 / 张 | 按输出档位计费；使用标准图片接口的 size 选择档位。 |
| 1K / 2K / 4K | gpt-image-2.5-sunburst | 0.2 / 0.3 / 0.5 / 张 | 按输出档位计费；使用标准图片接口的 size 选择档位。 |
| 2K | gpt-image-2-2K | 0.3 / 张 | 高规格图片，当前通过高规格上游路由。 |
| 4K | gpt-image-2-4K | 0.5 / 张 | 更高规格图片，耗时和返回体积通常更大。 |
1K 尺寸预设
1K 请求建议从下面这些尺寸里选。
| 比例 | 推荐 size |
|---|---|
| 1:1 | 1024x1024 |
| 16:9 | 1280x720 |
| 9:16 | 720x1280 |
| 3:2 | 1248x832 |
| 2:3 | 832x1248 |
| 4:3 | 1152x864 |
| 3:4 | 864x1152 |
| 5:4 | 1120x896 |
| 4:5 | 896x1120 |
| 21:9 | 1456x624 |
2K / 4K 常用写法示例：方图可尝试 2048x2048 或 4096x4096；横竖图请按业务比例放大。若上游返回不支持该尺寸，请改用相近比例或不传 size 让上游自动决定。Image2.5 的 flare / sunburst 也使用 size 选择 1K / 2K / 4K 档位。
6. 调用示例
文生图 cURL
curl https://ai.cozesf.cc/v1/images/generations \
-H "Authorization: Bearer <你的站内API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A tiny mint camera icon on a white background",
"size": "1024x1024"
}'2K / 4K 文生图 cURL
# 2K 示例，把 model 改成 gpt-image-2-4K 即可走 4K 档
curl https://ai.cozesf.cc/v1/images/generations \
-H "Authorization: Bearer <你的站内API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-2K",
"prompt": "A clean futuristic city poster, crisp details, cinematic light",
"size": "2048x2048",
"response_format": "url"
}'文生图 Python
import requests
url = "https://ai.cozesf.cc/v1/images/generations"
headers = {
"Authorization": "Bearer <你的站内API Key>",
"Content-Type": "application/json",
}
payload = {
"model": "gpt-image-2",
"prompt": "A tiny mint camera icon on a white background",
"size": "1024x1024",
}
resp = requests.post(url, headers=headers, json=payload, timeout=240)
resp.raise_for_status()
print(resp.json())文生图 JavaScript
const response = await fetch("https://ai.cozesf.cc/v1/images/generations", {
method: "POST",
headers: {
"Authorization": "Bearer <你的站内API Key>",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gpt-image-2",
prompt: "A tiny mint camera icon on a white background",
size: "1024x1024"
})
});
const result = await response.json();
console.log(result);图生图 JSON（传图片 URL）
curl https://ai.cozesf.cc/v1/images/edits \
-H "Authorization: Bearer <你的站内API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Turn this image into a clean green flat badge style illustration",
"size": "1024x1024",
"images": [
{ "image_url": "https://ai.cozesf.cc/logo.png" },
{ "image_url": "https://ai.cozesf.cc/logo.png" }
],
"response_format": "url"
}'图生图 Multipart（支持上传多张本地文件）
多图上传时保持字段名为 image，重复传多个文件字段；不要改成 image[]。
curl https://ai.cozesf.cc/v1/images/edits \
-H "Authorization: Bearer <你的站内API Key>" \
-F "image=@/path/to/logo.png" \
-F "image=@/path/to/reference.png" \
-F "model=gpt-image-2" \
-F "prompt=Turn this image into a clean green flat badge style illustration" \
-F "size=1024x1024" \
-F "response_format=url"7. Image2.5 兼容桥调用
gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst 对外仍使用标准图片接口。平台内部会把请求转换为 xibapi 的异步图片任务并等待完成，客户端不需要直接调用或轮询 /v1/videos。
| 模型 | 支持档位 | 调用规则 |
|---|---|---|
| gpt-image-2.5 | 仅 1K | 不传分辨率默认为 1K；不要传 2K / 4K。 |
| gpt-image-2.5-flare | 1K / 2K / 4K | 使用标准图片接口的 size 选择 1K / 2K / 4K 输出档位。 |
| gpt-image-2.5-sunburst | 1K / 2K / 4K | 使用标准图片接口的 size 选择输出档位，不要给模型名追加 -2K / -4K。 |
本站公网调用统一传 size，例如 1024x1024、2048x2048 或 4096x4096。图生图时将一个或多个公网图片 URL / Base64 放进顶层 images 数组，最多 8 张。aspect_ratio、image_size、resolution 仅用于上游内部任务格式。
Image2.5 文生图
curl https://ai.cozesf.cc/v1/images/generations \
-H "Authorization: Bearer <你的站内API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "A clean futuristic city poster, crisp details, cinematic light",
"size": "2048x2048",
"response_format": "url"
}'Image2.5 图生图
curl https://ai.cozesf.cc/v1/images/edits \
-H "Authorization: Bearer <你的站内API Key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-sunburst",
"prompt": "Turn the reference into a clean green flat badge style illustration",
"size": "1024x1024",
"images": [
{"image_url": "https://example.com/reference.png"}
],
"response_format": "url"
}'本站会等待上游任务完成后返回标准图片响应。客户端直接读取 data[0].url 或 data[0].b64_json，无需查询任务状态。
8. 响应格式
文生图和图生图当前都兼容同一套图片 API 响应结构。若显式传 response_format=url，优先读取 data[0].url；若显式传 b64_json，优先读取 data[0].b64_json。
注意：高规格上游可能把 PNG 直接放在 data[0].url 里，格式类似 data:image/png;base64,...。这仍然是 PNG，只是不是普通 https:// 图片链接。
{
"created": 1786438008,
"data": [
{
"url": "data:image/png;base64,iVBORw0KGgoAAA...",
"revised_prompt": "..."
}
],
"output_format": "png",
"size": "2048x2048"
}9. Base64 转图片示例
import base64
import requests
url = "https://ai.cozesf.cc/v1/images/generations"
headers = {
"Authorization": "Bearer <你的站内API Key>",
"Content-Type": "application/json",
}
payload = {
"model": "gpt-image-2",
"prompt": "A tiny mint camera icon on a white background",
"size": "1024x1024",
}
resp = requests.post(url, headers=headers, json=payload, timeout=240)
resp.raise_for_status()
result = resp.json()
item = result["data"][0]
if item.get("b64_json"):
b64_data = item["b64_json"]
else:
# Some upstreams return PNG as a data URL in data[0].url.
b64_data = item["url"].split(",", 1)[1]
with open("image2-result.png", "wb") as f:
f.write(base64.b64decode(b64_data))10. Markdown 格式文档
如果要发给开发、放进飞书/语雀/README，建议复制 Markdown 版本。顶部的 复制 Markdown 会复制完整 Markdown 文档。
# Image2 接入开发文档
Base URL: https://ai.cozesf.cc
- 文生图: POST /v1/images/generations
- 图生图: POST /v1/images/edits
- 1K: gpt-image-2 或 gpt-image-2.5-1k, 0.2 / 张
- 2K: gpt-image-2-2K, 0.3 / 张
- 4K: gpt-image-2-4K, 0.5 / 张
- 返回可能是普通 URL，也可能是 data:image/png;base64,...11. 计费说明
| 档位 | 当前组价格 | 说明 |
|---|---|---|
| 1K | 0.2 / 张 | 1K 档位；同步模型为 gpt-image-2 / gpt-image-2.5-1k，异步 Image2.5 模型按 1K 输出计费。 |
| 2K | 0.3 / 张 | 高规格档位，模型名 gpt-image-2-2K。 |
| 4K | 0.5 / 张 | 高规格档位，模型名 gpt-image-2-4K。 |
| Image2.5 flare / sunburst | 按输出档位 | 1K = 0.2 / 张，2K = 0.3 / 张，4K = 0.5 / 张。 |
12. 常见错误
| 现象 | 原因 | 处理方式 |
|---|---|---|
| 401 / 403 | 站内 API Key 无效，或者没有分配到正确分组。 | 换成站内有效 Key，并确认它属于 image2分组。 |
| 400 images endpoint requires an image model, got "image2" | 旧版本接入或非图片接口里把模型名写成了 image2。 | 同步接口改成 gpt-image-2 / gpt-image-2-2K / gpt-image-2-4K；Image2.5 新模型仍使用标准图片接口。 |
| 502 / 503 | 上游渠道暂时不可用，或传了当前未支持的尺寸。 | 检查模型名和尺寸是否匹配；高规格可尝试不传 size 或改用相近比例。 |
| images[].image_url is required | 正式公网入口的 JSON 图生图没有按当前要求传 images[].image_url。 | 把 JSON 请求改成 "images": [{"image_url": "https://..."}]。 |
| image is required | Multipart 图生图没有带图片，或者表单字段名写错了。 | 文件上传模式使用字段名 image。 |
| /v1/chat/completions 返回不可用 | 当前这条 Image2 接入文档只覆盖图片原生接口。 | 请改用 /v1/images/generations 或 /v1/images/edits。 |
| 403 预扣额度不足 | 上游账户余额不足以覆盖本次任务的预扣金额。 | 补充对应上游渠道余额；平台会在账号恢复可调度后自动使用该模型。 |