POST/v1/chat/completions

Gemini Chat 兼容：图片理解

通过 image_url 和本地 data URI 在 Chat 格式中输入图片。

API Key application/json

功能与适用场景

适合已有 Chat 多模态消息的客户端。输入是图片，返回 choices[].message.content 文字。

支持模型与组合

gemini-3.8-flash；示例 image.png，编码后完整 JSON 小于20 MB。

第一步：设置鉴权

使用青云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

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": [
        {
          "type": "text",
          "text": "描述图片中的主要景物。"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.png"
          }
        }
      ]
    }
  ]
}''')
payload["messages"][1]["content"][1]["image_url"]["url"] = "data:image/png;base64," + base64.b64encode(Path("image.png").read_bytes()).decode("ascii")
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
if len(encoded) >= 20_000_000:
    raise ValueError("示例限定完整请求小于20 MB，请压缩或拆分素材")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

idstring必填

响应字符串标识，用于日志关联；本目录不提供按该 ID 查询聊天任务的工作流。

objectstring必填

createdinteger必填

choicesarray必填

候选数组。非流读取 message.content / tool_calls，finish_reason 表示 stop / length / tool_calls / content_filter 等原因。不要假定 content 始终为非空字符串。

元素object

数组元素。

indexinteger

messageobject

rolestring必填

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

contentstring | array<object>必填

消息内容；分支：string / array<object>

finish_reasonstring

可选：stop / length / tool_calls / content_filter

usageobject必填

用量对象，可能因协议/流式缺失。prompt_tokens / completion_tokens / total_tokens；推理详情按模型返回。

prompt_tokensinteger必填

提示词 Token 数

completion_tokensinteger必填

补全 Token 数

total_tokensinteger必填

总 Token 数

prompt_tokens_detailsobject

cached_tokensinteger

text_tokensinteger

audio_tokensinteger

image_tokensinteger

completion_tokens_detailsobject

text_tokensinteger

audio_tokensinteger

reasoning_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
  }
}

常见错误与参考

需要原生 thoughtSignature、groundingMetadata 或精细媒体配置时改用原生。图片生成请去 Gemini Image，不能把这里的图片输入当作编辑动作。

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

Google 官方 generateContent 示例。

Gemini Chat 兼容：图片理解

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

请求

Body

路径、查询与 Header 参数

返回响应 200

常见错误与参考

返回响应 `200`