POST/v1/chat/completions

Gemini Chat 兼容：聊天与思考

使用 extra_body.google.thinking_config 的准确字段控制兼容聊天。

API Key application/json

功能与适用场景

适合沿用 Chat Completions 客户端并需要 Gemini 思考控制的应用。原生工具细节和签名多轮优先使用 generateContent。

支持模型与组合

gemini-3.8-flash。扩展使用 thinking_level=high、include_thoughts=true。2.5型号改用 thinking_budget，不使用 thinkingBudget。

第一步：设置鉴权

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

第二步：调用模型

POST https://top.qingyuntop.ai/v1/chat/completions

请求为 application/json。

Request

请求

/v1/chat/completions

Body

必填

Bodyobject

modelstring必填

必填，顶层，无默认值。填写当前账号可用的准确模型 ID；模型列表见模型选择页。

messagesarray必填

必填，顶层，无默认值。按时间顺序传入完整对话；至少一条 user 消息。Chat 接口不自动保存历史。

元素object

数组元素。

rolestring必填

消息角色；可选：system / user / assistant / tool / developer

contentstring | array<object>必填

消息内容必填的用户内容；纯文本可用字符串。多模态内容按顺序放 type=text 和 type=image_url 等块，不把 PDF 或 MP4 标成图片。；分支：string / array<object>

temperaturenumber

选填，0–2，传统聊天模型默认 1。仅对支持采样控制的模型设置；推理模型的默认值与支持范围不同。不要为最新模型机械添加此字段。；默认：1；范围：0–2

示例1

top_pnumber

选填，0–1，传统聊天模型默认 1。通常只调整 temperature 或 top_p 之一。；默认：1；范围：0–1

示例1

ninteger

选填，正整数，默认 1。示例 n=2 仅演示 gpt-4o 多候选；各候选都会消耗用量，不是重复发送两条请求。；默认：1；范围：1–∞

示例1

streamboolean

选填，顶层，默认 false。true 返回 SSE 事件，不能直接当作一个 JSON 解析。；默认：false

示例false

stopstring | array<string>

选填，字符串或字符串数组，无默认值。仅在支持该功能的模型使用；推理系列可能不支持。；分支：string / array<string>

max_tokensinteger

旧版输出长度字段；新推理模型使用 max_completion_tokens。不要同时提交两个长度字段。

presence_penaltynumber

选填字段；是否可用取决于当前模型和协议。；默认：0；范围：-2–2

示例0

frequency_penaltynumber

选填字段；是否可用取决于当前模型和协议。；默认：0；范围：-2–2

示例0

logit_biasobject

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

userstring

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

response_formatobject

选填，顶层。结构化输出使用 type=json_schema 与 json_schema 对象；json_object 只约束 JSON 格式，不保证字段。

typestring

可选：text / json_object / json_schema

json_schemaobject

JSON Schema 定义使用 JSON Schema 时必填。包含 name、strict=true、schema；所有 properties 列入 required，对每个对象设置 additionalProperties=false。可空字段用 null 联合类型。

toolsarray<object>

选填，顶层工具声明数组。函数使用 type=function、function.name 与 function.parameters；只声明你能执行的工具。

元素object

数组元素。

tool_choicestring | object

选填，无工具时默认 none，有工具时通常为 auto。支持 none / auto / required 或指定函数对象；模型支持范围可能不同。；分支：string / object

extra_bodyobject

googleobject

thinking_configobject

Gemini Chat 扩展，选填。使用 thinking_level、thinking_budget、include_thoughts 三个 snake_case 字段。Gemini 3 选等级，2.5 选预算，不混填。

stream_optionsobject

条件选填，仅 stream=true 时使用。include_usage=true 请求流末尾汇总用量，断线时可能收不到。

include_usageboolean

max_completion_tokensinteger

选填，顶层，无统一默认值。正整数，限制输出与内部推理合计 token；示例用 2048，推理任务可适当提高，不超过模型上限。

seedinteger

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

reasoning_effortstring

选填，顶层。示例 medium；o3/o4-mini 使用 low / medium / high。其他模型不要照抄全集枚举；未设置时采用模型默认。；可选：low / medium / high

modalitiesarray<string>

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

元素string

数组元素。；可选：text / audio

audioobject

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

voicestring

formatstring

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Content-Type`	Header	string	是	-	application/json
`Accept`	Header	string	是	-	application/json
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例application/json

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

payload = json.loads(r'''{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁、准确的 API 文档助手。"
    },
    {
      "role": "user",
      "content": "设计一个最多重试3次的订单查询流程：分别处理超时、429和业务失败，解释如何避免重复扣费。"
    }
  ],
  "extra_body": {
    "google": {
      "thinking_config": {
        "thinking_level": "high",
        "include_thoughts": true
      }
    }
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}''')
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 --no-buffer "https://top.qingyuntop.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output stream.sse

Response

返回响应 `200`

HTTP 响应

响应 200object

idstring必填

objectstring必填

createdinteger必填

choicesarray<object>必填

元素object

indexinteger

messageobject

rolestring必填

contentstring必填

finish_reasonstring

usageobject必填

prompt_tokensinteger必填

completion_tokensinteger必填

total_tokensinteger必填

响应示例json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\n\nHello there, how may I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

常见错误与参考

extra_body.google.thinkingConfig、thinking_config.thinkingBudget 都不是本入口正确写法。只用一种强度来源，避免 reasoning_effort 和扩展字段冲突。

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

Google 官方 generateContent 示例。原生思考配置。

Gemini Chat 兼容：聊天与思考

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

请求

Body

路径、查询与 Header 参数

返回响应 200

常见错误与参考

返回响应 `200`