API 参考

创建聊天对话

POST/v1/chat/completions

OpenAI Chat Completions 文本/工具兼容入口，支持图像输入的模型才可用 image_url。输出为文本/工具，能力、可选字段与价格取所选模型；stream=true 返回 SSE，可能含最终用量，结束 data: [DONE]。

鉴权与权限

使用当前 GloopAPI Key。模型、功能与权限以当前 Key 的目录及接口说明为准。

Authorization: Bearer $GLOOP_API_KEY

鉴权方案： BearerAuth

请求

请求体 · application/json

类型: object
必填字段: modelmessages

请求体必填

modelstring必填
模型 ID
messagesarray必填
对话消息列表
messages 子字段（1）
- []object选填
  [] 子字段（6）
  - rolestring必填
    消息角色
    
    枚举
    ["system","user","assistant","tool","developer"]
  - contentunion必填
    消息内容
    
    oneOf 分支 1
    类型: string
    oneOf 分支 2
    类型: array
    []object选填
    [] 子字段（6）
    typestring选填
    枚举
    ["text","image_url","input_audio","file","video_url"]
    textstring选填
    image_urlunion选填
    支持字符串 URL/Base64 或对象 {url, detail} 两种 wire 输入；仅支持图片输入的模型可用。不是保证所有模型支持视觉。
    
    oneOf 分支 1
    图片 URL 或 Base64 data URL。
    
    类型: string
    oneOf 分支 2
    对象输入至少提供 url；detail 默认在 Message.ParseContent 归一为 high，是否支持取所选视觉模型。
    
    类型: object
    分支必填： url
    urlstring必填
    图片 URL 或 base64
    
    detailstring选填
    枚举
    ["low","high","auto"]
    input_audioobject选填
    input_audio 子字段（2）
    datastring选填
    Base64 编码的音频数据
    
    formatstring选填
    枚举
    ["wav","mp3"]
    fileobject选填
    file 子字段（3）
    filenamestring选填
    file_datastring选填
    file_idstring选填
    video_urlstring选填
    实际 Message.ParseContent 读取的 wire 输入是视频 URL 字符串；仅支持视频输入的模型可用。{url: ...} 对象不会进入该解析器的内容/计量结果，不作为可用契约发布。
  - namestring选填
    发送者名称
  - tool_callsarray选填
    tool_calls 子字段（1）
    []object选填
    [] 子字段（3）
    idstring选填
    typestring选填
    functionobject选填
    function 子字段（2）
    namestring选填
    argumentsstring选填
  - tool_call_idstring选填
    工具调用 ID（用于 tool 角色消息）
  - reasoning_contentstring选填
    推理内容
temperaturenumber选填
采样温度具体支持与限制取所选模型，不保证统一默认值。
top_pnumber选填
核采样参数具体支持与限制取所选模型，不保证统一默认值。
ninteger选填
生成数量具体支持与限制取所选模型，不保证统一默认值。
streamboolean选填
是否流式响应

默认值
false
stream_optionsobject选填
Chat 流式用量选项；是否支持以及是否返回用量取决于所选模型。
stream_options 子字段（1）
- include_usageboolean选填
stopunion选填
停止序列
oneOf 分支 1
类型: string
oneOf 分支 2
类型: array
- []string选填
max_tokensinteger选填
最大生成 Token 数具体支持与限制取所选模型，不保证统一默认值。
max_completion_tokensinteger选填
最大补全 Token 数具体支持与限制取所选模型，不保证统一默认值。
presence_penaltynumber选填
具体支持与限制取所选模型，不保证统一默认值。
frequency_penaltynumber选填
具体支持与限制取所选模型，不保证统一默认值。
logit_biasobject选填
logit_bias 子字段（1）
- [key]number选填
userstring选填
toolsarray选填
tools 子字段（1）
- []object选填
  [] 子字段（2）
  - typestring选填
  - functionobject选填
    function 子字段（3）
    namestring选填
    descriptionstring选填
    parametersobject选填
    JSON Schema 格式的参数定义
tool_choiceunion选填
oneOf 分支 1
类型: string
枚举: ["none","auto","required"]
oneOf 分支 2
类型: object
- typestring选填
- functionobject选填
  function 子字段（1）
  - namestring选填
response_formatobject选填
response_format 子字段（2）
- typestring选填
  枚举
  ["text","json_object","json_schema"]
- json_schemaobject选填
  JSON Schema 定义
seedinteger选填
具体支持与限制取所选模型，不保证统一默认值。
reasoning_effortstring选填
推理强度 (用于支持推理的模型) 具体支持与限制取所选模型，不保证统一默认值。
modalitiesarray选填
modalities 子字段（1）
- []string选填
  枚举
  ["text","audio"]
audioobject选填
audio 子字段（2）
- voicestring选填
- formatstring选填
parallel_tool_callsboolean选填
是否允许并行工具调用，取决于所选模型。Chat 接受布尔值，Responses 接受兼容协议的 JSON 值。
storeboolean选填
是否允许保存请求与响应，取决于所选模型和服务支持范围；不代表提供通用对话存储接口。
prompt_cache_keystring选填
提示缓存关联标识；模型相关，不保证命中或支持。Chat 接受字符串，Responses 接受兼容协议 JSON 值。
prompt_cache_retentionunknown选填
提示缓存保留控制 JSON 值；模型相关，平台不赋予统一枚举、默认值或缓存保留保证。
service_tierunknown选填
请求服务层级，可能影响费用；默认忽略，仅在支持此参数时生效。支持值取决于所选模型。

响应与错误

HTTP 200

成功创建响应

application/json

类型: object
额外属性: false

idstring选填
objectstring选填
createdinteger选填
modelstring选填
choicesarray选填
choices 子字段（1）
- []object选填
  额外属性
  false
  [] 子字段（3）
  - indexinteger选填
  - messageobject选填
    额外属性
    false
    message 子字段（5）
    rolestring必填
    枚举
    ["assistant"]
    contentstring选填允许 null
    Text response content.
    
    tool_callsarray选填
    tool_calls 子字段（1）
    []object选填
    [] 子字段（3）
    idstring选填
    typestring选填
    functionobject选填
    function 子字段（2）
    namestring选填
    argumentsstring选填
    reasoning_contentstring选填允许 null
    refusalstring选填允许 null
  - finish_reasonstring选填
    枚举
    ["stop","length","tool_calls","content_filter"]
usageobject选填
usage 子字段（5）
- prompt_tokensinteger选填
  提示词 Token 数
- completion_tokensinteger选填
  补全 Token 数
- total_tokensinteger选填
  总 Token 数
- prompt_tokens_detailsobject选填
  prompt_tokens_details 子字段（4）
  - cached_tokensinteger选填
  - text_tokensinteger选填
  - audio_tokensinteger选填
  - image_tokensinteger选填
- completion_tokens_detailsobject选填
  completion_tokens_details 子字段（3）
  - text_tokensinteger选填
  - audio_tokensinteger选填
  - reasoning_tokensinteger选填
system_fingerprintstring选填

text/event-stream

类型: string
说明: SSE 事件流，协议事件/用量/结束符取当前接口，错误可能在流内。

{
  "type": "string",
  "description": "SSE 事件流，协议事件/用量/结束符取当前接口，错误可能在流内。"
}

HTTP 400

请求参数错误

application/json

类型: object

errorobject选填
error 子字段（4）
- messagestring选填
  错误信息
- typestring选填
  错误类型
- paramstring选填允许 null
  相关参数
- codestring选填允许 null
  错误代码

HTTP 401

Key 缺失、无效、过期或已撤销。

application/json

类型: object
必填字段: error

errorobject必填
error 子字段（4）
- codestring选填
- messagestring选填
- typestring选填
- request_idstring选填

HTTP 403

IP、账户、模型或工具权限不足。

application/json

类型: object
必填字段: error

errorobject必填
error 子字段（4）
- codestring选填
- messagestring选填
- typestring选填
- request_idstring选填

HTTP 429

请求频率限制

application/json

类型: object

errorobject选填
error 子字段（4）
- messagestring选填
  错误信息
- typestring选填
  错误类型
- paramstring选填允许 null
  相关参数
- codestring选填允许 null
  错误代码

HTTP 500

鉴权或数据存储内部失败。

application/json

类型: object
必填字段: error

errorobject必填
error 子字段（4）
- codestring选填
- messagestring选填
- typestring选填
- request_idstring选填