功能与支持模型

gemini-3-pro-image 支持网页搜索；gemini-3.1-flash-image 支持网页与图片搜索。Flash Lite Image、2.5 Flash Image 不使用本页工具。搜索是否触发、能找到哪些素材以及生成是否准确仍由模型和搜索结果决定。

本页使用原生格式，以保留 groundingMetadata 等引用信息。搜索不是通用的任意 URL 下载接口；不能用它代替需要明确上传的产品图。Flash 图片搜索目前不支持通过搜索获取现实人物照片的用途。

第一步：设置鉴权

使用请求头 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。示例在 tools 中启用 google_search，再设置 searchTypes.webSearch 和 searchTypes.imageSearch。

参数与组合

字段与类型位置、填写规则与限制
contents[].parts[].text；string文生图必填、编辑时填写修改指令；无默认值。描述主体、构图、需要保留的元素及文字内容。
tools；object[]可选；JSON 顶层数组。搜索生图使用 [{"google_search": {}}]；Pro/Flash 支持网页搜索，Flash 可进一步配置 searchTypes.imageSearch；Lite/2.5 不填。
generationConfig.imageConfig.aspectRatio；string可选；字符串。省略时参考输入比例，否则通常为 1:1。通用 10 种与 Flash 扩展 4 种见模型表；不填写像素宽高。
generationConfig.imageConfig.imageSize；string可选；3.x 默认 1K。Pro：1K/2K/4K；Flash：512/1K/2K/4K；Lite 使用 1K；2.5 省略。512 是字符串，不带 px 或 K；K 必须大写。

tools 是顶层数组，google_search 是其中的工具对象；Flash 的 searchTypes 在 google_search 内，两个搜索类型的值均为 {}。只使用网页搜索时可传 "tools":[{"google_search":{}}]；换成 Pro 时使用这一网页搜索配置，不能保留 imageSearch。

可切换代码示例

点击横向标签切换语言。cURL 使用 Bash，需支持 --fail-with-body；文件/历史示例还需 jq 和 base64。Python 需安装 requests；Node.js 需 20 或更新版本，保存为 .mjs。示例的 600 秒超时是客户端设置，不是生成时限承诺。建议每个示例使用独立目录；同名输出文件会覆盖。

set -euo pipefail
cat > request-template.json <<'JSON'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "结合搜索资料和图片参考，绘制一张帝王蝶的自然科普插图，准确展示翅膀纹理与颜色，旁边用简短中文说明其特征。"
        }
      ]
    }
  ],
  "tools": [
    {
      "google_search": {
        "searchTypes": {
          "webSearch": {},
          "imageSearch": {}
        }
      }
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "3:2",
      "imageSize": "2K"
    }
  }
}
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

结果、引用与图片保存

图片与其他原生请求一样位于 candidates[].content.parts[].inlineData，Python/Node.js 自动保存。本页还必须保留完整的 response.json，查看候选中的 groundingMetadata，包括可选的 groundingChunks、groundingSupports、imageSearchQueries 和 searchEntryPoint。字段可能因是否实际搜索而缺省。

若响应提供搜索建议和来源引用，在产品中展示结果时按 Google 的搜索展示要求呈现对应引用与 searchEntryPoint.renderedContent。渲染 HTML 时需采用受限、安全的展示方式，不将任意返回 HTML 直接注入主页面；只下载图片会丢失引用上下文。

图片搜索的来源块可位于 groundingChunks[].image：sourceUri 为应标注的来源网页，imageUri 为图片资源，title、domain 为可选来源信息。向用户提供可识别的来源网页链接；如果同时展示参考源图，点击源图应直接到达其来源网页，不经过多次点击或中间预览器。不要用直接图片地址替代来源网页署名。

常见错误与参考

工具不支持时确认模型为 Pro 或 Flash，并核对 imageSearch 是否只用于 Flash。搜索可能带来额外用量，以本站控制台价格与记录为准，不按普通纯图片请求估算固定费用。官方参考：网页搜索辅助生图、图片搜索、来源块字段。