API 使用指南
图片生成
用 Images 端点生成和编辑图片，或在 Responses 中使用内置图片工具。
LynShen 提供两种生成图片的方式：
| 方式 | 端点 | 适用场景 |
|---|---|---|
| Images API | POST /v1/images/generations、POST /v1/images/edits | 只需要图片。参数简单，兼容 OpenAI SDK 的 images 接口。 |
| Responses 内置工具 | POST /v1/responses，tools 中加入 image_generation | 需要模型在对话中按需生成图片。 |
Chat Completions 不能返回图片。模型在 Chat 中输出图片时，网关返回 HTTP 502 unsupported_output_media。
用 /v1/models 查询可用的图片模型。模型广场中的示例有 gpt-image-2、grok-imagine-image。
生成图片
curl https://api.lynshen.org/v1/images/generations \
-H "Authorization: Bearer $LYNSHEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "黎明时分的灯塔，水彩风格",
"size": "1024x1024",
"quality": "medium"
}' | python3 -c "import sys,json,base64; d=json.load(sys.stdin); open('out.png','wb').write(base64.b64decode(d['data'][0]['b64_json']))"请求字段
| 字段 | 说明 |
|---|---|
model | 必填。 |
prompt | 必填。 |
n | 生成数量，默认 1。大于 1 时，网关把请求拆成 n 个独立请求并行执行，每个单独计费。部分失败时，只返回成功的图片。 |
size、quality、background、output_format、moderation、input_fidelity、style | 图片选项。网关原样转发，可用值由上游模型决定。 |
output_compression | 0 到 100 的整数。 |
stream | 设为 true 时返回 SSE。要求 n 为 1。 |
响应
{
"created": 1791731777,
"data": [{ "b64_json": "iVBORw0KGgo...", "revised_prompt": "……" }],
"output_format": "png",
"quality": "medium",
"size": "1024x1024",
"usage": { "input_tokens": 10, "output_tokens": 100, "total_tokens": 110 }
}- 图片通常以 Base64 形式放在
b64_json中。上游只返回链接时，条目中是url。网关不托管图片。链接会过期，请及时下载。 revised_prompt是上游改写后的提示词。上游没有返回时，没有这个字段。output_format、quality、size、background是上游报告的实际值。所有图片的值相同时才出现在顶层。
编辑图片
用 multipart/form-data 上传图片：
curl https://api.lynshen.org/v1/images/edits \
-H "Authorization: Bearer $LYNSHEN_API_KEY" \
-F model="gpt-image-2" \
-F prompt="在海面上加一艘红色小船" \
-F 'image[]=@input.png' \
-F mask=@mask.pngimage或image[]可以出现 1 到 16 次。第一张是主图。mask可选，最多一个，使用 PNG 透明区域标出要编辑的位置。
也可以用 JSON 提交图片引用：
curl https://api.lynshen.org/v1/images/edits \
-H "Authorization: Bearer $LYNSHEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "在海面上加一艘红色小船",
"images": [{ "image_url": "https://example.com/input.png" }],
"mask": { "image_url": "data:image/png;base64,iVBORw0KGgo..." }
}'每个 images 条目和 mask 必须恰好包含 image_url 或 file_id 之一。image_url 可以是 HTTPS 地址，也可以是 Base64 数据 URL。
流式返回
图片生成可能需要几十秒。设置 "stream": true 可以让连接保持活动：
curl -N https://api.lynshen.org/v1/images/generations \
-H "Authorization: Bearer $LYNSHEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-image-2","prompt":"黎明时分的灯塔","stream":true}': heartbeat
event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"iVBORw0KGgo...","created_at":1791730261,"output_format":"png","size":"1024x1024","usage":{...}}
data: [DONE]- 网关立即发送一个心跳注释。之后 15 秒内没有数据时，再发送一个心跳。
- 每张完成的图片对应一个
image_generation.completed事件。编辑接口的事件名是image_edit.completed。 - 网关不发送局部预览图。
- 失败时发送
event: error，数据为{"type":"error","error":{...}}，然后是data: [DONE]。
Responses 内置图片工具
import base64, os
from openai import OpenAI
client = OpenAI(base_url="https://api.lynshen.org/v1", api_key=os.environ["LYNSHEN_API_KEY"])
response = client.responses.create(
model="gpt-5.5",
input="画一座黎明时分的灯塔，并用一句话描述它。",
tools=[{"type": "image_generation", "size": "1024x1024", "quality": "low"}],
)
for item in response.output:
if item.type == "image_generation_call" and item.result:
with open("lighthouse.png", "wb") as f:
f.write(base64.b64decode(item.result))
print(response.output_text)只有支持图片工具的上游模型可以使用这种方式。模型不支持时，网关返回错误。
注意事项
- 请求体上限为 50 MiB，包括上传的图片。
- 网关不提供
POST /v1/images/variations。 - 不同图片模型支持的
size、quality等取值不同。不支持的取值由上游返回错误。