Gemini 3.1 Flash Image Preview 图像生成

• 模型名：gemini-3.1-flash-image-preview（固定）
• 能力：文生图、图生图（最多 14 张参考图）、最高 4K 输出、极端宽高比、可选 Google 搜索增强

不要用 /v1/chat/completions 调用本模型；误用会返回 400 并提示改用 Images API。

调用方式

方式	端点	适用场景
同步（推荐）	POST https://apimaster.ai/v1/images/generations	一次 HTTP 请求返回图片 URL（平台服务端轮询上游）
异步	POST https://apimaster.ai/v1/images/generations/async → GET https://apimaster.ai/v1/tasks/{task_id}?model=gemini-3.1-flash-image-preview	长任务、自建队列；提交后立即拿 task_id

快速开始（同步）

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "赛博朋克风格的城市夜景，霓虹灯闪烁",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

成功响应（OpenAI 兼容）

{
  "created": 1782633696,
  "data": [
    { "url": "https://apimaster.ai/imgs/1782633695067198543.jpg" }
  ]
}

• 2K / 4K 可能耗时 30–120 秒；请将 HTTP 读超时设为 ≥ 180 秒
• 返回 URL 有时效，请及时下载或转存

异步流程

1. 提交

curl -s "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

提交响应

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}

2. 轮询

curl -s "https://apimaster.ai/v1/tasks/TASK_ID?model=gemini-3.1-flash-image-preview" \
  -H "Authorization: Bearer YOUR_API_KEY"

进行中：

{
  "data": {
    "status": "in_progress"
  }
}

完成时取图：data.result.images[0].url（字符串 URL）。

阶段	典型 status
提交成功	submitted（仅出现在提交响应）
排队 / 生成中	pending、processing、in_progress
成功	completed、succeeded
失败	failed、error、cancelled

• 首次轮询建议延迟 10–20 秒，之后每 3–5 秒 一次
• 4K 任务请预留更长的轮询时间

认证

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在 控制台 创建 API Key。

请求参数

字段	类型	必填	说明
model	string	是	固定 gemini-3.1-flash-image-preview
prompt	string	是	画面描述
size	string	否	宽高比；见下表
resolution	string	否	0.5K / 1K / 2K / 4K，默认 1K；大小写均可
n	integer	否	生成张数，仅支持 1（纯数字，勿加引号）
image_urls	array	否	参考图 URL 或 base64 data URI，图生图
google_search	boolean	否	启用 Google 文字搜索增强，默认 false
google_image_search	boolean	否	启用 Google 图片搜索增强，需配合 google_search: true

size 支持的比例

auto、1:1、3:2、2:3、4:3、3:4、16:9、9:16、5:4、4:5、21:9，以及极端比例 1:4、4:1、1:8、8:1。

resolution 与计费档位

值	约等于	参考单价（1K 基准）
0.5K	~512px	与 1K 同档
1K	~1024px	基准档
2K	~2048px	约为 1K 的 4/3
4K	~4096px	约为 1K 的 2 倍

实际扣费 = 渠道单价 × 分辨率倍率 × 分组倍率。以 模型广场 或控制台日志为准。

image_urls（图生图）

• 最多 14 张（建议：物体参考 ≤10，角色参考 ≤4）
• 单张 ≤ 10MB；格式 jpeg / png / webp
• 支持公网 URL 或完整 data URI：data:image/jpeg;base64,...

请求示例

文生图（16:9 + 2K）

{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "resolution": "2K",
  "n": 1
}

图生图 + 搜索增强

{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "将参考图风格化为赛博朋克海报",
  "size": "4:3",
  "resolution": "1K",
  "image_urls": ["https://example.com/photo.jpg"],
  "google_search": true,
  "google_image_search": true
}

错误响应

HTTP	含义
400	参数错误，或误用 chat 端点
401	API Key 无效
402	余额不足
429	限流
408	同步请求轮询上游超时（可降分辨率或改走异步）
500 / 502	服务或上游异常

无效 size / resolution 等参数错误，在单渠道环境下有时表现为 500 而非 400。

注意事项

1. 对外仅使用模型 id gemini-3.1-flash-image-preview。
2. prompt 违规可能被拒绝，通常不计费（以控制台为准）。
3. 使用日志中会记录 result_url（图片预览）与 request_data.resolution / effective_resolution。
4. 价格因渠道与 resolution 而异，以 模型广场 或控制台为准。