图片生成 API 接入

本文面向接入 GreatWall Link 图片生成能力的开发者，可直接提供给 AI 编程助手生成调用代码。
文档覆盖接口选择、请求参数、同步与异步调用、结果下载和错误处理。

一、能力概述

支持 OpenAI 和 Gemini 两类图片接口：

协议	文生图	图生图	异步
OpenAI	支持	支持	支持
Gemini	支持	支持	支持

同步请求会等待图片生成完成后返回。异步请求需要三个步骤：

text

1. 创建任务   POST /v1/images/generations 或 /v1/images/edits
2. 轮询状态   GET  /v1/images/tasks/{task_id}
3. 读取结果   从 result 或 /v1/images/tasks/{task_id}/files/{index} 获取图片

图片生成不支持流式响应。高质量图片可能耗时较长，建议客户端设置较长的超时时间，或使用异步模式。

二、基础信息

项目	值
API 基础地址	`https://api.gwlink.cc`
认证方式	`Authorization: Bearer <你的 API Key>`
JSON 请求	`Content-Type: application/json`
OpenAI 图生图	`multipart/form-data`
图片响应	URL 或 Base64，取决于 `response_format`

开始前请准备：

已注册并登录 GreatWall Link。
已创建令牌分组为 image-video 的 API Key。
账户有可用额度。
需要运行 Python 示例时，安装 Python 3.9 或更高版本。

创建 API Key 的方法请参考创建 API Key。模型名称、可用尺寸和实时价格请以模型广场为准。

WARNING

API Key 只会在创建时完整显示。请勿将真实密钥写入代码、提交到 Git 或发送给他人。

三、接口和模型

协议	功能	请求接口
OpenAI	文生图	`POST /v1/images/generations`
OpenAI	图生图	`POST /v1/images/edits`
Gemini	文生图	`POST /v1beta/models/{model}:generateContent`
Gemini	图生图	`POST /v1beta/models/{model}:generateContent`

model 使用模型广场中显示的名称。平台可以配置自定义模型名，但必须已经配置对应渠道、模型映射和价格。

所有创建任务和查询任务请求都需要：

http

Authorization: Bearer YOUR_API_KEY

四、接口一：OpenAI 文生图

text

POST /v1/images/generations

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称
`prompt`	string	是	图片描述，建议写清主体、场景、风格和构图
`n`	integer	否	生成数量，默认 `1`，上限由平台配置决定
`size`	string	否	图片尺寸，必须使用模型支持的尺寸
`quality`	string	否	`auto`、`low`、`medium` 或 `high`，以模型支持为准
`output_format`	string	否	`png`、`jpeg` 或 `webp`，以模型支持为准
`output_compression`	integer	否	`0-100`，仅对 `jpeg` 和 `webp` 生效
`moderation`	string	否	`auto` 或 `low`，以模型支持为准
`response_format`	string	否	`url` 或 `b64_json`，默认 `url`
`stream`	boolean	否	必须省略或设置为 `false`

请求示例

bash

curl "https://api.gwlink.cc/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "赛博朋克城市雨夜，霓虹招牌特写，电影画幅",
    "n": 1,
    "size": "1536x1024",
    "quality": "high",
    "response_format": "url"
  }'

响应

默认返回 URL：

json

{
  "created": 1780000000,
  "data": [
    {
      "url": "https://api.gwlink.cc/v1/images/tasks/imgtask_xxx/files/0",
      "b64_json": "",
      "revised_prompt": ""
    }
  ]
}

传入 "response_format": "b64_json" 时，图片位于 data[].b64_json，url 为空。

异步请求

在同步请求的基础上增加：

http

Prefer: respond-async

创建任务和轮询方式见异步任务。

五、接口二：OpenAI 图生图

text

POST /v1/images/edits

请求必须使用 multipart/form-data，不能发送 JSON 请求体。

bash

curl "https://api.gwlink.cc/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留主体构图，将背景修改为雪山日落" \
  -F "image=@input.png" \
  -F "n=1" \
  -F "size=1536x1024" \
  -F "response_format=url"

字段	类型	必填	说明
`model`	string	是	模型名称
`prompt`	string	是	图片编辑要求
`image`	file	是	输入图片，可重复传递多张
`mask`	file	否	蒙版图片，是否生效取决于模型
`n`	integer	否	输出数量，默认 `1`
`size`	string	否	输出尺寸
`quality`	string	否	输出质量
`response_format`	string	否	`url` 或 `b64_json`，默认 `url`
`stream`	boolean	否	必须省略或设置为 `false`

多图请求只需重复 image 字段：

bash

-F "image=@input-1.png" \
-F "image=@input-2.png"

异步图生图同样增加 Prefer: respond-async 请求头。

六、接口三：Gemini 文生图和图生图

两种 Gemini 图片请求都使用：

text

POST /v1beta/models/{model}:generateContent

请求中的 generationConfig.responseModalities 必须包含 IMAGE。不要调用 :streamGenerateContent，也不要传 ?alt=sse。

Gemini 文生图

bash

curl "https://api.gwlink.cc/v1beta/models/gemini-2.5-flash-image:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "生成一张雨夜霓虹街道的电影感图片"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "1:1"}
    },
    "response_format": "url"
  }'

只需要图片时，将 responseModalities 设置为 ["IMAGE"]。

Gemini 图生图

输入图片放在 contents[].parts[].inlineData 中，data 必须是纯 Base64，不要带 data:image/png;base64, 前缀。

json

{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "将图片改成水彩插画风格，保留主体细节"},
      {
        "inlineData": {
          "mimeType": "image/png",
          "data": "BASE64_IMAGE"
        }
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"]
  },
  "response_format": "url"
}

多图输入时，在 parts 中增加多个 inlineData。异步 Gemini 请求增加 Prefer: respond-async。

Gemini 响应

Gemini 保留原生响应结构：

`response_format`	图片位置
未传或 `url`	`candidates[].content.parts[].fileData.fileUri`
`b64_json`	`candidates[].content.parts[].inlineData.data`

Gemini 的 response_format 是平台参数，只用于控制返回格式，不会透传给上游。

七、异步任务

创建任务

异步请求成功返回 200 OK，响应头包含：

http

Location: /v1/images/tasks/imgtask_xxx
Preference-Applied: respond-async
Retry-After: 2

响应体：

json

{
  "id": "imgtask_xxx",
  "object": "image.generation.task",
  "status": "queued",
  "created_at": 1780000000
}

轮询任务

bash

curl "https://api.gwlink.cc/v1/images/tasks/imgtask_xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

查询任务必须使用同一用户的 API Key。建议按照 Retry-After: 2，每隔约 2 秒查询一次。

`status`	含义	后续动作
`queued`	已进入队列	继续轮询
`processing`	正在生成	继续轮询
`settling`	正在完成计费结算	继续轮询
`succeeded`	生成成功，结果位于 `result`	读取结果
`failed`	生成失败，错误位于 `error`	读取错误并结束
`expired`	图片资源已过期	重新生成

result 保留原协议结构：OpenAI 结果在 result.data，Gemini 结果在 result.candidates。

查询时指定返回格式

bash

curl "https://api.gwlink.cc/v1/images/tasks/imgtask_xxx?response_format=b64_json" \
  -H "Authorization: Bearer YOUR_API_KEY"

不传参数：使用创建任务时的格式；创建时也未传则默认 url。
传 url 或 b64_json：只覆盖本次响应，不修改任务记录。
传其他值：返回 400，错误码为 invalid_response_format。

同一个任务不允许并发进行多个 Base64 查询。上一次查询未结束时再次查询返回 409 image_task_result_busy；URL 查询不受此限制。

八、图片文件和保存策略

任务成功后，按图片序号访问文件：

text

GET /v1/images/tasks/{task_id}/files/{index}

bash

curl "https://api.gwlink.cc/v1/images/tasks/imgtask_xxx/files/0" \
  -o result.png

图片 URL 默认公开，不需要 API Key；响应缓存 24 小时。
index 从 0 开始。任务未成功时返回 404，过期后返回 410。
图片默认保存 24h；平台每天清理过期图片。
清理后任务标记为 expired，任务查询和图片 URL 同时失效。

后台会在“任务日志 → 图片任务”记录异步任务，以及同步任务落盘后的模型、状态、额度、耗时和结果图。

九、完整 Python 示例

bash

pip install requests

设置 API Key：

powershell

$env:GWLINK_API_KEY="你的 API Key"

下面的示例调用 OpenAI 文生图接口并保存第一张结果图：

python

import base64
import os

import requests


API_URL = "https://api.gwlink.cc/v1/images/generations"
API_KEY = os.environ["GWLINK_API_KEY"]
PAYLOAD = {
    "model": "gpt-image-2",
    "prompt": "赛博朋克城市雨夜，霓虹招牌特写，电影画幅",
    "n": 1,
    "size": "1536x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "url",
}


response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=PAYLOAD,
    timeout=1000,
)
response.raise_for_status()
item = response.json()["data"][0]

if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
elif item.get("url"):
    image_response = requests.get(item["url"], timeout=120)
    image_response.raise_for_status()
    image_bytes = image_response.content
else:
    raise RuntimeError("响应中没有可用的图片数据")

with open("result.png", "wb") as file:
    file.write(image_bytes)

print("已保存 result.png")

十、错误码和接入检查

HTTP 状态码	错误码或情况	处理
`400`	`invalid_response_format`	只使用 `url` 或 `b64_json`
`400`	`streaming is not supported for image generation`	删除 `stream: true`
`401`	API Key 无效	检查 Key、`Bearer` 前缀和令牌分组
`404`	`image_task_not_found`	检查任务 ID 和用户是否一致
`409`	`image_task_result_busy`	等待上一次 Base64 查询结束
`410`	`image_task_expired`	重新生成图片
`415`	图生图格式错误	使用 `multipart/form-data`

接入前确认：

[ ] model 使用模型广场中的可用名称。
[ ] size 使用该模型支持的尺寸。
[ ] OpenAI 图生图使用 multipart/form-data，Gemini 图片使用 inlineData。
[ ] Gemini 的 responseModalities 包含 IMAGE。
[ ] 不使用流式接口；异步请求添加 Prefer: respond-async。
[ ] 异步任务处理 failed 和 expired 状态，并设置轮询超时。
[ ] URL 结果直接下载，Base64 结果避免并发读取同一任务。

其它使用方式

想通过网页直接生成图片，请阅读 GPT Image2 画廊绘图教程。

VS Code 插件

Cherry Studio

图片生成 API 接入

一、能力概述

二、基础信息

三、接口和模型

四、接口一：OpenAI 文生图

请求参数

请求示例

响应

异步请求

五、接口二：OpenAI 图生图

六、接口三：Gemini 文生图和图生图

Gemini 文生图

Gemini 图生图

Gemini 响应

七、异步任务

创建任务

轮询任务

查询时指定返回格式

八、图片文件和保存策略

九、完整 Python 示例

十、错误码和接入检查

其它使用方式

图片生成 API 接入 ​

一、能力概述 ​

二、基础信息 ​

三、接口和模型 ​

四、接口一：OpenAI 文生图 ​

请求参数 ​

请求示例 ​

响应 ​

异步请求 ​

五、接口二：OpenAI 图生图 ​

六、接口三：Gemini 文生图和图生图 ​

Gemini 文生图 ​

Gemini 图生图 ​

Gemini 响应 ​

七、异步任务 ​

创建任务 ​

轮询任务 ​

查询时指定返回格式 ​

八、图片文件和保存策略 ​

九、完整 Python 示例 ​

十、错误码和接入检查 ​

其它使用方式 ​

图片生成 API 接入

一、能力概述

二、基础信息

三、接口和模型

四、接口一：OpenAI 文生图

请求参数

请求示例

响应

异步请求

五、接口二：OpenAI 图生图

六、接口三：Gemini 文生图和图生图

Gemini 文生图

Gemini 图生图

Gemini 响应

七、异步任务

创建任务

轮询任务

查询时指定返回格式

八、图片文件和保存策略

九、完整 Python 示例

十、错误码和接入检查

其它使用方式