图片生成与编辑 API

使用 /v1/images/generations 根据文本提示词生成图片，使用 /v1/images/edits 根据输入图片和提示词编辑图片。两个端点均采用兼容 OpenAI Images API 的请求格式；具体可用能力取决于 Flatkey 服务实际开放的模型和渠道。

Gemini 图片模型使用 Gemini 原生 generateContent 端点，不能通过这些 OpenAI Images 端点调用。请参阅 Gemini 图片模型操作手册。

生成图片

端点

POST https://router.flatkey.ai/v1/images/generations

请求头

请求头	值
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

JSON 请求体参数

string

必填

Flatkey 服务实际开放的图片模型 ID，例如 "gpt-image-2"。

string

必填

对要生成图片的文本描述。

string

输出尺寸，例如 "1024x1024"。支持值取决于模型。

string

输出质量："low"、"medium" 或 "high"。省略时使用上游默认值；质量越高，耗时和用量越大。

string

背景处理，例如 "transparent" 或 "opaque"，是否支持取决于模型。

string

输出格式，例如 "png"、"jpeg" 或 "webp"，是否支持取决于模型。

integer

输出压缩级别，是否支持取决于模型。

string

内容审核档位，是否支持取决于模型。

string

gpt-image-2 的结果固定返回在 data[].b64_json 中，不提供托管图片 URL，也不支持 response_format: "url"。

integer

请求的图片数量。gpt-image-2 的上游图片工具目前不接受 n，因此每次请求固定返回一张图片；如需多张，请发起多次请求。

boolean

设置为 true 时返回 SSE 流；省略时返回同步响应。

请求示例

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="A futuristic city skyline at dusk, cyberpunk style",
    size="1024x1024",
    quality="high",
)

Path("generated.png").write_bytes(
    base64.b64decode(response.data[0].b64_json)
)

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A futuristic city skyline at dusk, cyberpunk style",
  size: "1024x1024",
  quality: "high",
});

writeFileSync(
  "generated.png",
  Buffer.from(response.data[0].b64_json, "base64"),
);

curl https://router.flatkey.ai/v1/images/generations \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A serene forest clearing with morning mist and sunbeams",
    "size": "1024x1024",
    "quality": "high"
  }'

编辑图片

/v1/images/edits 使用 multipart/form-data 上传待编辑图片和编辑指令。

端点

POST https://router.flatkey.ai/v1/images/edits

请求头

请求头	值
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`multipart/form-data`；使用 curl 时由 `-F` 自动生成并附带 boundary

表单参数

参数	类型	必填	说明
`model`	string	是	Flatkey 服务实际开放的图片模型 ID，例如 `gpt-image-2`。
`prompt`	string	是	对图片的编辑指令。
`image`	file	是	待编辑图片，支持 PNG、JPEG 和 WebP。多图可使用 `image[]` 或 `image[0]`、`image[1]`。
`mask`	file	否	用于局部重绘的蒙版；透明区域是需要重绘的区域。
`size`	string	否	输出尺寸，支持值取决于模型。
`quality`	string	否	输出质量：`low`、`medium` 或 `high`。
`stream`	boolean	否	设置为 `true` 时返回 SSE 流。

请求示例

curl https://router.flatkey.ai/v1/images/edits \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=在图片中央添加一颗黄色的小星星" \
  -F "image=@input.png" \
  -F "mask=@mask.png"

mask 是可选参数。省略它即可根据提示词编辑整张图片。不要手动添加 Content-Type 请求头；curl 会根据 -F 参数自动设置正确的 multipart boundary。

如果提供的蒙版已损坏、无法读取或超过服务限制，请求会直接失败，不会退化为整图编辑。

响应

同步生成和编辑请求返回相同的响应结构。Flatkey 以 Base64 数据返回图片；gpt-image-2 不提供托管图片 URL。

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "revised_prompt": "Add a small yellow five-pointed star in the center...",
      "url": ""
    }
  ]
}

响应字段

integer

请求完成时的 Unix 时间戳。

array

图片对象数组。

显示图片对象

string

Base64 编码的图片数据。

string

模型改写后实际使用的提示词。

string

gpt-image-2 固定为空；本接口不提供托管 URL。

编辑请求的输入图片也会计入模型用量，因此图片编辑通常比纯文本生成图片消耗更多用量。

流式响应

在生成请求的 JSON 请求体中设置 stream: true，或在编辑请求中添加 -F "stream=true"，即可接收 text/event-stream 响应。最终事件包含图片结果，随后返回 data: [DONE]。

事件	含义
`image_generation.completed`	图片生成完成。
`image_edit.completed`	图片编辑完成。
`[DONE]`	响应流结束。

流式支持情况取决于所选模型和渠道。对于同步的高质量请求，建议将客户端超时设置为至少 150 秒。

​生成图片

​端点

​请求头

​JSON 请求体参数

​请求示例

​编辑图片

​端点

​请求头

​表单参数

​请求示例

​响应

​响应字段

​流式响应

生成图片

端点

请求头

JSON 请求体参数

请求示例

编辑图片

端点

请求头

表单参数

请求示例

响应

响应字段

流式响应