POST/v1/chat/completions

Chat：JSON Schema 结构化输出

通过 response_format 获得符合结构的 JSON 文本，并处理截断与拒绝。

API Key application/json

功能与适用场景

适合实体提取、表单解析和结构化分类。输出 JSON 仍放在 message.content 字符串中，先检查结束状态再解析。

支持模型与组合

本例使用 gpt-4.1 与 strict JSON Schema。不是所有 Chat 兼容模型都实现相同 schema 子集。

第一步：设置鉴权

使用青云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<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": "gpt-4.1",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁、准确的 API 文档助手。"
    },
    {
      "role": "user",
      "content": "从“北京现在22摄氏度”提取城市和温度。"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "temperature_c": {
            "type": "number"
          }
        },
        "required": [
          "city",
          "temperature_c"
        ],
        "additionalProperties": false
      }
    }
  }
}''')
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 查询聊天任务的工作流。

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

常见错误与参考

必填字段遗漏、嵌套对象未设置 additionalProperties=false、使用不支持的 schema 关键词会导致400。json_object 是较弱的 JSON 模式，不能作为字段完整性的保证。

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

OpenAI 公共 API 规范。

Chat：JSON Schema 结构化输出

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

常见错误与参考

返回响应 `200`