curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一张现代 API 平台首页插图,白底,青蓝色块,干净留白",
"n": 1,
"size": "1536x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-vip",
"prompt": "一张高端科技发布会主视觉,超宽画幅,冷暖对比光,细节丰富",
"n": 1,
"size": "3808x1632",
"quality": "high"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-4-0-250828",
"prompt": "一张白底产品主图,干净布光,商业摄影风格",
"n": 1,
"size": "1024x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "一张极简 API 文档封面图,白色背景,清晰几何构图",
"n": 1,
"size": "2K",
"aspect_ratio": "16:9",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "参考图片中的商品,生成一张白底电商主图,保持材质和颜色一致",
"n": 1,
"size": "1536x1024",
"quality": "high",
"image": [
"https://example.com/input.png"
]
}'
import requests
resp = requests.post(
"https://www.geeknow.top/v1/images/generations/async",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url",
},
timeout=60,
)
print(resp.json())
const response = await fetch("https://www.geeknow.top/v1/images/generations/async", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2-pro",
prompt: "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
n: 1,
size: "3840x2160",
quality: "high",
response_format: "url",
}),
});
console.log(await response.json());
{
"id": "task_img_abc123",
"task_id": "task_img_abc123",
"object": "image.generation.task",
"model": "gpt-image-2-vip",
"status": "queued",
"created_at": 1735689600
}
{
"created": 1735689600,
"data": [
{
"url": "https://example.com/images/task_img_abc123.png",
"revised_prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富"
}
],
"size": "3840x2160",
"quality": "high",
"background": "opaque",
"output_format": "png",
"usage": {
"input_tokens": 15,
"total_tokens": 211,
"output_tokens": 196,
"input_tokens_details": {
"text_tokens": 15
},
"output_tokens_details": {
"image_tokens": 196
}
}
}
{
"error": {
"message": "prompt is required",
"type": "invalid_request_error",
"param": "prompt",
"code": "invalid_request"
}
}
图像异步生成
图像异步生成 API
使用 POST /v1/images/generations/async 提交图像异步生成任务,并通过任务查询接口获取最终结果。
POST
https://www.geeknow.top
/
v1
/
images
/
generations
/
async
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一张现代 API 平台首页插图,白底,青蓝色块,干净留白",
"n": 1,
"size": "1536x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-vip",
"prompt": "一张高端科技发布会主视觉,超宽画幅,冷暖对比光,细节丰富",
"n": 1,
"size": "3808x1632",
"quality": "high"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-4-0-250828",
"prompt": "一张白底产品主图,干净布光,商业摄影风格",
"n": 1,
"size": "1024x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "一张极简 API 文档封面图,白色背景,清晰几何构图",
"n": 1,
"size": "2K",
"aspect_ratio": "16:9",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "参考图片中的商品,生成一张白底电商主图,保持材质和颜色一致",
"n": 1,
"size": "1536x1024",
"quality": "high",
"image": [
"https://example.com/input.png"
]
}'
import requests
resp = requests.post(
"https://www.geeknow.top/v1/images/generations/async",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url",
},
timeout=60,
)
print(resp.json())
const response = await fetch("https://www.geeknow.top/v1/images/generations/async", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2-pro",
prompt: "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
n: 1,
size: "3840x2160",
quality: "high",
response_format: "url",
}),
});
console.log(await response.json());
{
"id": "task_img_abc123",
"task_id": "task_img_abc123",
"object": "image.generation.task",
"model": "gpt-image-2-vip",
"status": "queued",
"created_at": 1735689600
}
{
"created": 1735689600,
"data": [
{
"url": "https://example.com/images/task_img_abc123.png",
"revised_prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富"
}
],
"size": "3840x2160",
"quality": "high",
"background": "opaque",
"output_format": "png",
"usage": {
"input_tokens": 15,
"total_tokens": 211,
"output_tokens": 196,
"input_tokens_details": {
"text_tokens": 15
},
"output_tokens_details": {
"image_tokens": 196
}
}
}
{
"error": {
"message": "prompt is required",
"type": "invalid_request_error",
"param": "prompt",
"code": "invalid_request"
}
}
图像异步生成 API
/v1/images/generations/async 用于提交图像异步生成任务。请求体采用 JSON 格式;提交成功后保存返回的任务 ID,并通过 GET /v1/images/generations/async/{taskId} 查询进度和最终结果。
- 异步入口为
POST /v1/images/generations/async。 - 查询入口为
GET /v1/images/generations/async/{taskId}。 - 当前已验证可用模型包括
gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、Doubao Seedream 系列和 Gemini 图像模型。 - 异步任务的
image目前只接受公网http(s)图片 URL,不支持 Base64 或data:URI。 - 成功提交后优先读取
id、task_id或taskId作为后续查询 ID。 - Gemini 图像模型走异步入口时,
size表示图片清晰度,按1K/2K传入。 prompt建议控制在1到4000个字符。n表示生成数量,常用范围为1到10。
方法与路径
POST /v1/images/generations/async
请求示例
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一张现代 API 平台首页插图,白底,青蓝色块,干净留白",
"n": 1,
"size": "1536x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-vip",
"prompt": "一张高端科技发布会主视觉,超宽画幅,冷暖对比光,细节丰富",
"n": 1,
"size": "3808x1632",
"quality": "high"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-4-0-250828",
"prompt": "一张白底产品主图,干净布光,商业摄影风格",
"n": 1,
"size": "1024x1024",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "一张极简 API 文档封面图,白色背景,清晰几何构图",
"n": 1,
"size": "2K",
"aspect_ratio": "16:9",
"quality": "auto",
"response_format": "url"
}'
curl -X POST https://www.geeknow.top/v1/images/generations/async \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-pro",
"prompt": "参考图片中的商品,生成一张白底电商主图,保持材质和颜色一致",
"n": 1,
"size": "1536x1024",
"quality": "high",
"image": [
"https://example.com/input.png"
]
}'
import requests
resp = requests.post(
"https://www.geeknow.top/v1/images/generations/async",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"model": "gpt-image-2-pro",
"prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
"n": 1,
"size": "3840x2160",
"quality": "high",
"response_format": "url",
},
timeout=60,
)
print(resp.json())
const response = await fetch("https://www.geeknow.top/v1/images/generations/async", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2-pro",
prompt: "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富",
n: 1,
size: "3840x2160",
quality: "high",
response_format: "url",
}),
});
console.log(await response.json());
响应示例
{
"id": "task_img_abc123",
"task_id": "task_img_abc123",
"object": "image.generation.task",
"model": "gpt-image-2-vip",
"status": "queued",
"created_at": 1735689600
}
{
"created": 1735689600,
"data": [
{
"url": "https://example.com/images/task_img_abc123.png",
"revised_prompt": "一张电影级科技城市全景海报,清晨雾气,纵深透视,细节丰富"
}
],
"size": "3840x2160",
"quality": "high",
"background": "opaque",
"output_format": "png",
"usage": {
"input_tokens": 15,
"total_tokens": 211,
"output_tokens": 196,
"input_tokens_details": {
"text_tokens": 15
},
"output_tokens_details": {
"image_tokens": 196
}
}
}
{
"error": {
"message": "prompt is required",
"type": "invalid_request_error",
"param": "prompt",
"code": "invalid_request"
}
}
认证
Authorization: Bearer YOUR_API_KEY
Body
string
required
模型名称。当前已验证可用值包括
gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、doubao-seedream-4-0-250828、doubao-seedream-4-5-251128、doubao-seedream-5-0-260128、gemini-3-pro-image-preview、gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview、gemini-3.1-flash-lite-image。VIP 模型名请使用 gpt-image-2-vip,不要传 gpt-image-vip。string
required
文本提示词,用于描述想要生成的图片。建议控制在
1 到 4000 个字符。integer
生成数量。常用范围为
1 到 10;未传时默认为 1。string
输出尺寸。
gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 支持 gpt-image-2 与 gpt-image-2-pro 的全部基础、2K 和 4K 实际 WxH 尺寸。其它 GPT Image 模型的常见值包括 1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840、1920x1080、1080x1920。gpt-image-2-vip 使用独立尺寸约束,常见值还包括 2304x1728、3264x2448、3504x2336、3808x1632。Gemini 图像模型中,size 对应 Gemini 原生 generationConfig.imageConfig.imageSize 清晰度字段,不传像素尺寸;可传 1K 或 2K。gemini-3-pro-image-preview 支持 1K / 2K;gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview 与 gemini-3.1-flash-lite-image 会实际回落为 1K。string
图片比例。Gemini 异步生图支持该字段,传入什么比例就按什么比例生成。常见值包括
1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9。array<string>
可选参考图输入。数组成员当前只接受公网可访问的
http(s) 图片 URL。string
质量等级。通用值为
low、medium、high、auto;gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 还支持 xhigh 和 max。未传时默认 auto。string
返回格式。常见值为
url、b64_json。gpt-image-2-vip 不建议依赖该字段强制切换返回格式。Response
string
异步任务 ID。后续可传入
GET /v1/images/generations/async/{taskId} 查询任务状态。string
异步任务 ID 的兼容字段。部分响应会使用下划线命名。
string
异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
string
任务对象类型,通常为
image.generation.task。string
任务使用的图像模型,例如
gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、doubao-seedream-4-0-250828、gemini-3-pro-image-preview 或 gemini-3.1-flash-lite-image。string
任务状态。提交后通常为
queued,轮询中可能出现 processing / in_progress。integer
任务创建时间戳。
integer
最终结果对象的生成时间戳。
string
最终结果对象的输出尺寸或清晰度,例如
1024x1024、1536x1024、3840x2160 或 Gemini 的 2K。string
最终结果对象的质量等级,例如
low;gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 也可能返回 xhigh 或 max。string
最终结果对象的背景信息,例如
opaque。string
最终结果对象的图片格式,例如
png。object
最终结果对象里的 token 统计信息。
string
最终结果对象中
response_format = url 时返回的图片 URL。string
最终结果对象中
response_format = b64_json 时返回的图片 Base64 数据。string
部分上游会改写提示词并返回在这个字段里。
与同步接口的区别
| 项目 | 同步生图 | 异步生图 |
|---|---|---|
| 路径 | /v1/images/generations | /v1/images/generations/async |
| 请求字段 | model、prompt、n、size、image、quality、response_format | 按目标模型填写;异步 image 目前只接受公网 http(s) URL |
| 返回结构 | created + data[] | 先返回任务对象;任务完成后查询接口直接返回结果对象 |
| 适用场景 | 响应时间较短的生图请求 | 高分辨率、参考图或耗时较长的生图请求 |
使用建议
- 如果调用方需要等待图片直接返回,优先使用同步接口
/v1/images/generations。 - 如果任务耗时较长,或业务需要提交后异步处理,使用
/v1/images/generations/async。 - Gemini 图像模型走异步入口时使用 OpenAI Images 兼容 JSON,不使用
/v1beta/models/{model}:generateContent的 Gemini 原生请求体。 - 提交成功后保存
id、task_id或taskId,并调用任务查询接口轮询最终结果。 gpt-image-2-pro的常见高分辨率尺寸包括2048x2048、3840x2160、2160x3840。gpt-image-2.5-flare与gpt-image-2.5-sunburst支持全部基础、2K和4K尺寸,具体WxH映射见各自生成页面。gpt-image-2.5-flare与gpt-image-2.5-sunburst的quality还支持xhigh和max。gpt-image-2-vip的size必须满足:每条边是16px倍数,最长边不超过3840px,长短边比例不超过3:1,总像素数在655,360到8,294,400之间。- Gemini 图像模型的
size表示清晰度:gemini-3-pro-image-preview可传1K或2K;gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview与gemini-3.1-flash-lite-image会按1K处理。 - Gemini 异步生图的
aspect_ratio传入什么比例就按什么比例生成,常见值包括1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9。 - 异步参考图请使用公网
http(s)URL,不能传 Base64 / data URI。