API 对接文档¶

本文档面向需要直接对接图片生成 API 的客户。所有示例均使用 cURL，示例中的完整图片 base64 均以占位符表示。

基本信息¶

项目	说明
Base URL	`联系客服获取`
认证方式	`Authorization: Bearer <api_key>`
超时时间	同步/流式请求建议 300s
响应格式	JSON / Server-Sent Events (SSE)

export BASE_URL="联系客服获取"
export API_KEY="sk-your-api-key"

已验证请求方式¶

截至 2026-05-16，图片接口已验证以下请求方式：

请求方式	说明	已验证接口
同步	请求保持连接，完成后一次性返回最终图片	OpenAI Images `stream:false`；Gemini `generateContent`
流式	SSE 返回进度/中间事件，最后返回最终图片	OpenAI Images `stream:true`；Gemini `streamGenerateContent`

可用模型¶

模型 ID	协议	说明
`gpt-image-2`	OpenAI Images	支持同步、流式、multipart 图生图
`gemini-2.5-flash-image`	Gemini v1beta	支持同步和流式
`gemini-3-pro-image`	Gemini v1beta	支持同步和流式
`gemini-3.1-flash-image`	Gemini v1beta	支持同步和流式

不要使用 gemini-*-flash-image-preview 作为前端图片模型名。

认证验证¶

OpenAI Images Key 可用以下接口验证：

curl "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

Gemini 图片生成接口支持直连 /v1beta。如果只验证模型列表，部分部署可能未开放裸 /v1beta/models；应以实际生成接口验证为准。

隐私说明¶

本文档只保留同步和流式接口。不会保存您的数据。

一、OpenAI Images API¶

1.1 同步文生图¶

stream:false 时，请求完成后一次性返回 JSON。图片在 data[0].b64_json。

curl --max-time 300 "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A simple black checkmark icon on a white background",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "response_format": "b64_json",
    "stream": false
  }'

响应结构：

{
  "created": 1778903610,
  "data": [
    {
      "b64_json": "<base64 encoded image data>",
      "revised_prompt": "...",
      "output_format": "png"
    }
  ]
}

1.2 流式文生图¶

stream:true 时返回 SSE。客户端应优先使用 event: image_generation.completed 中的顶层 b64_json。

curl -N --max-time 300 "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A simple red square icon on a white background",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "response_format": "b64_json",
    "stream": true,
    "partial_images": 1
  }'

响应事件示例：

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"<base64>"}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"<base64>"}

1.3 Multipart 图生图¶

单张参考图使用字段 image，多张参考图使用 image[0]、image[1]，最多 16 张。

curl --max-time 300 "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Change the circle to green while keeping a plain white background" \
  -F "image=@ref.png" \
  -F "size=1024x1024" \
  -F "quality=low" \
  -F "response_format=b64_json"

多张参考图：

curl --max-time 300 "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Blend these references into one clean product image" \
  -F "image[0]=@ref-1.png" \
  -F "image[1]=@ref-2.png" \
  -F "size=1024x1024" \
  -F "quality=low" \
  -F "response_format=b64_json"

二、Gemini v1beta 图片接口¶

Gemini 图片接口使用直连 /v1beta 路径：

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

请求体必须包含 generationConfig.responseModalities: ["IMAGE"]。最终图片位于 candidates[].content.parts[].inlineData.data。

2.1 同步文生图¶

curl --max-time 300 "$BASE_URL/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Draw a simple yellow star icon on a white background" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

响应结构：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<base64 encoded image data>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "gemini-3.1-flash-image"
}

2.2 流式文生图¶

流式接口会先返回 queued/running 文本块，最终返回 inlineData.data。不要因为中间文本块没有图片就判定失败。

curl -N --max-time 300 "$BASE_URL/v1beta/models/gemini-3.1-flash-image:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Draw a simple cyan hexagon icon on a white background" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

响应事件示例：

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"image task queued (0%)"}]},"index":0}],"modelVersion":"gemini-3.1-flash-image"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"image task running (10%)"}]},"index":0}],"modelVersion":"gemini-3.1-flash-image"}

data: {"candidates":[{"content":{"role":"model","parts":[{"inlineData":{"mimeType":"image/png","data":"<base64>"}}]},"finishReason":"STOP","index":0}],"modelVersion":"gemini-3.1-flash-image"}

data: [DONE]

2.3 带参考图¶

参考图使用 inlineData，data 为不带 data:image/...;base64, 前缀的 base64。

IMAGE_B64="$(base64 -w 0 ref.png)"

curl --max-time 300 "$BASE_URL/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [
      {
        \"role\": \"user\",
        \"parts\": [
          { \"text\": \"Turn this reference image into a watercolor style image\" },
          {
            \"inlineData\": {
              \"mimeType\": \"image/png\",
              \"data\": \"$IMAGE_B64\"
            }
          }
        ]
      }
    ],
    \"generationConfig\": {
      \"responseModalities\": [\"IMAGE\"],
      \"imageConfig\": {
        \"aspectRatio\": \"1:1\",
        \"imageSize\": \"1K\"
      }
    }
  }"

参数参考¶

OpenAI Images 参数¶

参数	类型	说明
model	string	当前前端使用 `gpt-image-2`
prompt	string	图片提示词
n	number	生成数量，默认 1
size	string	输出尺寸，例如 `1024x1024`、`1536x1024`、`1024x1536`、`3840x2160`、`auto`
quality	string	`low`、`medium`、`high`、`auto`
response_format	string	`b64_json` 或 `url`
stream	boolean	是否使用 OpenAI Images SSE
partial_images	number	流式中间图数量，当前建议 `1`

Gemini 图片参数¶

参数	说明
contents[].parts[].text	图片提示词
contents[].parts[].inlineData	参考图 base64
generationConfig.responseModalities	必须包含 `IMAGE`
imageConfig.aspectRatio	`auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`5:4`、`4:5`、`21:9`、`1:4`、`4:1`、`1:8`、`8:1`
imageConfig.imageSize	`1K`、`2K`、`4K`

错误处理¶

状态码	含义	建议处理
400	参数错误	检查请求体和模型名
401	API Key 无效或缺失	检查 `Authorization`
402	余额不足	充值或更换 Key
403	无权访问	检查 Key 分组和模型权限
404	接口不存在或路径错误	检查 Base URL 和路径
413	请求体过大	减少参考图数量或压缩图片
429	请求过多	降低并发，指数退避
500+	服务端或上游错误	稍后重试

OpenAI Images 错误格式：

{
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is required"
  }
}

Gemini 错误格式：

{
  "error": {
    "code": 400,
    "message": "Request body is empty",
    "status": "INVALID_ARGUMENT"
  }
}