POST/v1/chat/completions

Chat：网页搜索与引用

使用搜索专用模型及 web_search_options 获取带来源的回答。

API Key application/json

功能与适用场景

适合最新事件查询。搜索结果会增加外部资料上下文，应用需展示来源并检查引用是否支持结论。

支持模型与组合

示例 gpt-4o-mini-search-preview，为搜索专用预览型号；使用前先确认账号仍可用。普通 GPT Chat 模型不能仅通过空 web_search_options 保证联网。

第一步：设置鉴权

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

第二步：调用模型

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

请求为 application/json。

Chat Completions 兼容协议

调用与返回说明

适合已经依赖 Chat Completions 的客户端和模型。新建 OpenAI 集成时优先确认模型支持 Responses API，再决定是否使用此兼容协议。

请求时注意

model 和 messages 是基本必填项；tools、tool_choice、response_format 等能力参数按场景发送，不是所有模型都支持。
模型 ID 以 GET /v1/models 的返回为准。示例中的固定模型名只是格式示例，不代表当前账号一定可用。
对于新推理模型，优先使用 max_completion_tokens；max_tokens 是旧字段，且可能与推理模型不兼容。

返回时注意

非流式文本读取 choices[0].message.content，并检查 choices[0].finish_reason。
Chat Completions 的工具调用位于 choices[].message.tool_calls，不能与 Responses 的 output[].type=function_call 混读。

Request

请求

/v1/chat/completions

Body

必填

Bodyobject

modelstring必填

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

web_search_optionsobject

搜索专用模型的选填配置。示例 search_context_size=medium；可选 low / medium / high，默认 medium。不能用它让任意普通聊天模型联网。

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

stream_optionsobject

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

include_usageboolean

stopstring | array<string>

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

max_tokensinteger

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

max_completion_tokensinteger

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

presence_penaltynumber

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

示例0

frequency_penaltynumber

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

示例0

logit_biasobject

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

userstring

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

toolsarray<object>

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

元素object

数组元素。

typestring

functionobject

函数工具必填；name 为唯一函数名，description 解释用途，parameters 为 JSON Schema。严格模式 strict=true；不要把模型生成的参数直接作为任意代码执行。

namestring

descriptionstring

parametersobject

JSON Schema 格式的参数定义

tool_choicestring | object

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

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 联合类型。

seedinteger

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

reasoning_effortstring

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

modalitiesarray<string>

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

元素string

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

audioobject

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

voicestring

formatstring

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer 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'''{
  "model": "gpt-4o-mini-search-preview",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁、准确的 API 文档助手。"
    },
    {
      "role": "user",
      "content": "查询最近一次国际空间站任务新闻并列出来源。"
    }
  ],
  "web_search_options": {
    "search_context_size": "medium"
  }
}''')
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/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 查询聊天任务的工作流。

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>

namestring

发送者名称

tool_callsarray<object>

元素object

数组元素。

idstring

typestring

functionobject

namestring

argumentsstring

tool_call_idstring

工具调用 ID（用于 tool 角色消息）

reasoning_contentstring

推理内容

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_example",
  "object": "chat.completion",
  "model": "MODEL_ID_FROM_V1_MODELS",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我可以帮助你。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 12,
    "total_tokens": 30
  }
}

Chat Completions 兼容协议

调用与返回说明

适合已经依赖 Chat Completions 的客户端和模型。新建 OpenAI 集成时优先确认模型支持 Responses API，再决定是否使用此兼容协议。

请求时注意

model 和 messages 是基本必填项；tools、tool_choice、response_format 等能力参数按场景发送，不是所有模型都支持。
模型 ID 以 GET /v1/models 的返回为准。示例中的固定模型名只是格式示例，不代表当前账号一定可用。
对于新推理模型，优先使用 max_completion_tokens；max_tokens 是旧字段，且可能与推理模型不兼容。

返回时注意

非流式文本读取 choices[0].message.content，并检查 choices[0].finish_reason。
Chat Completions 的工具调用位于 choices[].message.tool_calls，不能与 Responses 的 output[].type=function_call 混读。

常见错误与参考

搜索型模型对采样参数有限制，本例省略 temperature / top_p。需要 Responses 内置 web_search 时转到对应协议，不能混入 Chat tools。

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

OpenAI 公共 API 规范。

Chat：网页搜索与引用

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

常见错误与参考

返回响应 `200`