POST/v1beta/models/gemini-2.5-pro:generateContent

Gemini：JSON Schema 结构化输出

通过 responseMimeType 和 responseJsonSchema 生成指定结构。

API Key application/json

功能与适用场景

用于字段提取、分类和机器解析。本页只约束输出结构，事实和业务合法性仍需应用检查。

支持模型与组合

示例 gemini-3.8-flash。JSON Schema 支持为子集，复杂 schema 先简化；切换型号时核对支持。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。

第二步：调用模型

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

请求为 application/json。

Request

请求

/v1beta/models/gemini-2.5-pro:generateContent

Body

必填

Bodyobject

contentsarray必填

必填，顶层 content 数组。role 使用 user / model，parts 保持原始顺序；下一轮重新发送历史。

元素object

数组元素。

partsarray<object>

每条 content 必填。文本 {text:...}；媒体 {inlineData:{mimeType,data}}；一张图片一个 part，顺序影响引用。

元素object

数组元素。

textstring

inline_dataobject

mime_typestring必填

datastring必填

generationConfigobject

选填，顶层对象。输出长度、采样、结构化格式、思考和语音设置分别放在对象对应子字段。

responseModalitiesarray<string>必填

元素string

responseMimeTypestring

JSON 输出时设为 application/json；配合 responseJsonSchema 或 responseSchema，只选择一种 schema。默认输出文本。

responseJsonSchemaobject

JSON 输出的结构 schema，选填，示例使用 object / properties / required / additionalProperties。不能同时设置 responseSchema。

temperaturenumber

topPnumber

topKinteger

maxOutputTokensinteger

选填，正整数，无统一默认。限制输出 token，思考也占用预算；示例 4096。

stopSequencesarray<string>

元素string

数组元素。

model（路径）string必填

必填，在 /v1beta/models/{model}:动作中填写；generateContent 请求体无需重复 model。

safetySettingsarray<object>

选填字段；是否可用取决于当前模型和协议。

元素object

数组元素。

categorystring

thresholdstring

toolsarray<object>

选填，顶层工具数组。按本页选择 functionDeclarations、googleSearch、urlContext 或 codeExecution；名称区分大小写。

元素object

数组元素。

systemInstructionobject

选填，顶层。parts 中填写文本指令，不放入 generationConfig。

partsarray<object>

元素object

数组元素。

路径、查询与 Header 参数

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

请求示例application/json

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "从“北京现在22摄氏度”提取城市和温度。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseJsonSchema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        },
        "temperature_c": {
          "type": "number"
        }
      },
      "required": [
        "city",
        "temperature_c"
      ],
      "additionalProperties": false
    }
  },
  "systemInstruction": {
    "parts": [
      {
        "text": "以简洁、准确的中文回答。"
      }
    ]
  }
}''')
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

candidatesarray

候选数组，可缺省或为空。按 index 区分，遍历 content.parts；text 是文字，inlineData 是媒体，functionCall 是函数调用。不能只取第一个 part。

元素object

数组元素。

contentobject

rolestring

partsarray<object>

元素object

数组元素。

finishReasonstring

流式中间片可缺省。STOP 为正常结束，MAX_TOKENS 为截断，SAFETY / RECITATION 等需显示相应限制；缺少最终原因时不能认定内容完整。

safetyRatingsarray<object>

元素object

数组元素。

usageMetadataobject

可缺省的用量对象，含 promptTokenCount、candidatesTokenCount、totalTokenCount，思考详情按实际返回；流式汇总不逐片相加。

promptTokenCountinteger

candidatesTokenCountinteger

totalTokenCountinteger

promptFeedbackobject

blockReasonstring

提示词被拦截时可能出现；这时可能没有 candidates。先检查拦截原因，不把空候选当作空白的成功答案。

常见错误与参考

responseJsonSchema 与 responseSchema 二选一；不将 OpenAI response_format 放在 Gemini 顶层，也不使用 Interactions response_format 结构。

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。

Google 官方 generateContent 示例。

Gemini：JSON Schema 结构化输出

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

请求

Body

路径、查询与 Header 参数

返回响应 200

常见错误与参考

返回响应 `200`