POST/v1beta/models/gemini-2.5-flash-image:generateContent

Gemini Image 文生图

使用文字提示生成一张宣传海报，并在本地保存生成的图片。示例采用稳定版 Flash Image，适用于大多数首次接入场景。

API Key application/json

功能与支持模型

输入文字，输出图片和可选的文字说明。默认示例使用 gemini-3.1-flash-image、1:1、1K。相同请求可将路径模型替换为 gemini-3-pro-image，用于复杂设计；使用 gemini-3.1-flash-lite-image 时保留 1K 与常用比例。完整差异见模型与参数。

提示词明确主体、背景、视角、图片用途，以及图片中需要准确呈现的文字。一次请求可以返回多个内容块，不保证提示词要求的张数；客户端必须按实际图片块处理。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格；基础地址为 https://top.qingyuntop.ai。

第二步：调用模型

POST https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-image:generateContent

Content-Type 为 application/json，请求同步返回结果。示例中的中文提示可以直接替换，不需要上传参考图。

Request

请求

/v1beta/models/gemini-2.5-flash-image:generateContent

Body

必填

Bodyobject

contentsarray<object>必填

元素object

partsarray<object>

元素object

textstring

inline_dataobject

mime_typestring必填

datastring必填

generationConfigobject必填

responseModalitiesarray<string>必填

元素string

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`key`	Query	string	是	-	YOUR_API_KEY
`Content-Type`	Header	string	是	-	application/json

请求示例application/json

set -euo pipefail
cat > request-template.json <<'JSON'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "生成一张现代咖啡店的宣传海报，画面是一杯陶瓷杯装的拿铁，米白色背景，标题清晰写着“早安咖啡”，自然晨光，简洁留白。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "1K"
    }
  }
}
JSON
cp request-template.json request.json
[ "$(wc -c < request.json)" -lt 20000000 ] || { echo "请求超过 20 MB，请压缩图片或缩短历史" >&2; exit 1; }
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

返回结果与图片保存

三种示例都保存本轮 request.json 与 response.json。Python/Node.js 还会遍历 candidates[].content.parts[]、跳过 thought=true 的内容并将图片写入 output-1.png 等文件。cURL 的 response.json 仍是 JSON，按图片保存解码，不要直接改成 .png。

正常生图应得到非思考 inlineData 图片及 finishReason=STOP。仅有 HTTP 200、只有文字或空候选都不足以认定图片已经生成。需要继续修改这张海报时，保留这两个 JSON 文件并进入多轮编辑。

常见错误与参考

没有图片时检查模型是否为完整的 *-image ID、是否选择 IMAGE 输出以及响应中的限制说明；图片被拦截时不要无限重发。高分辨率请查看宽高比与高清输出，连接等待方式见流式消费。官方参考：文生图指南。