POST/v1/chat/completions

Chat：声明工具并获取函数调用

用 tools 定义函数，获取模型生成的工具名称、参数和调用 ID。

API Key application/json

功能与适用场景

模型根据用户问题建议调用你的业务函数。本例只声明查询北京天气的工具，不会访问真实天气服务。

支持模型与组合

示例 gpt-4.1，使用 strict=true 和 required 强制本轮产生工具调用。切换型号前确认其工具与严格模式支持。

第一步：设置鉴权

使用青云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；模型列表见模型选择页。

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

选填，顶层工具声明数组。函数使用 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": "gpt-4.1",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁、准确的 API 文档助手。"
    },
    {
      "role": "user",
      "content": "请查询北京的天气。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询给定城市的天气；示例仅支持北京。",
        "strict": true,
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "enum": [
                "北京"
              ]
            }
          },
          "required": [
            "city"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "required"
}''')
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必填

objectstring必填

createdinteger必填

choicesarray<object>必填

元素object

indexinteger

messageobject

rolestring必填

contentstring必填

finish_reasonstring

usageobject必填

prompt_tokensinteger必填

completion_tokensinteger必填

total_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 混读。

常见错误与参考

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

OpenAI 公共 API 规范。

Chat：声明工具并获取函数调用

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

常见错误与参考

返回响应 `200`