GPT 5.2
本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。
接口
POST /gpt-5-2/v1/chat/completions
完整 URL: https://ai.modelfold.online/gpt-5-2/v1/chat/completions
鉴权：所有请求都需要
Authorization: Bearer <API_KEY>请求头。
WARNING
⚠️ 仅支持对话调用
该模型目前仅支持对话调用，暂未适配 Agent 场景。若将其接入 Agent 使用，可能会出现请求报错或结果异常。
GPT-5-2 API 是新一代多模态模型，具备卓越的推理能力，支持文本和图像输入，提供联网搜索增强功能并支持调节推理力度。
功能特性
| 特性 | 描述 |
|---|---|
| 多模态 | 支持文本和图像输入 |
| 实时搜索 | 启用联网搜索增强 |
| 推理力度 | 可调节推理力度级别 |
| 灵活角色 | 支持多种消息角色 |
统一媒体文件格式
::: caution 在 messages 参数的 content 数组中，目前仅支持图像。所有图像文件使用相同的格式结构：
type字段始终为"image_url"image_url字段名称保持不变- 唯一变化的是
url值，它指向相应的图像地址
例如：{ type: 'image_url', image_url: { url: '...' } } 结构。
:::
Tools 参数
tools 参数是一个可选数组，允许您启用联网搜索增强。
联网搜索
使用此格式启用联网搜索增强：
json
{
"type": "function",
"function": {
"name": "web_search"
}
}这将通过联网搜索启用实时信息检索。
响应示例
json
{
"id": "chatcmpl-example-123",
"object": "chat.completion",
"created": 1741569952,
"model": "gpt-5-2",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好，有什么可以帮你的吗？",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 50,
"total_tokens": 60
}
}错误处理
请检查响应体，不要只看 HTTP 状态码。错误有两种形态：{"code": ..., "msg": "..."}（如 401 API key 无效、402 积分不足、429 频率超限；HTTP 状态可能仍为 200），或 {"error": {"type": "...", "message": "..."}}。
请求参数
请求体 (application/json)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
messages | array<object> | 是 | 消息对象数组。每个消息都有一个角色和内容。 统一媒体文件格式： 在 content 数组中，目前仅支持图像。所有图像文件使用相同的格式结构： - type 字段始终为 "image_url"- image_url 字段名称保持不变- 唯一变化的是 url 值，它指向相应的图像地址例如： { type: 'image_url', image_url: { url: '...' } } 结构。 |
messages[].role | string | 是 | 消息角色 - developer: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。在 o1 模型及更新版本中，developer 消息取代了之前的 system 消息。 - system: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。在 o1 模型及更新版本中，请使用 developer 消息代替。 - user: 最终用户发送的消息，包含提示或额外的上下文信息。 - assistant: 模型响应用户消息而发送的消息。 可选值： developer / system / user / assistant。 示例：developer。 |
messages[].content | `array<object | object>` | 是 |
tools | array<object> | 否 | 可选，模型可以调用的工具数组。支持联网搜索：{"type": "function", "function": {"name": "web_search"}} - 通过联网搜索启用实时信息检索。 |
tools[].type | string | 是 | 固定为 function。 可选值：function。 示例：function。 |
tools[].function | object | 是 | — |
tools[].function.name | string | 是 | 固定为 web_search。 可选值：web_search。 示例：web_search。 |
reasoning_effort | string | 否 | 推理的力度。低力度响应更快，高力度响应更慢但解决更复杂的问题。默认为 "high"。 默认值："high"。 可选值：low / high。 示例：high。 |
请求示例
bash
curl -X POST "https://ai.modelfold.online/gpt-5-2/v1/chat/completions" \
-H "Authorization: Bearer $MODELFOLD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "web_search"
}
}
],
"reasoning_effort": "high"
}'json
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "web_search"
}
}
],
"reasoning_effort": "high"
}响应
200 — 请求成功。返回标准的聊天完成格式。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 否 | 聊天完成的唯一标识符 示例：chatcmpl-example-123。 |
object | string | 否 | 对象类型 示例：chat.completion。 |
created | integer | 否 | 完成创建时的 Unix 时间戳 示例：1677652288。 |
model | string | 否 | 模型名称 示例：gpt-5-2。 |
choices | array<object> | 否 | 完成选项数组 |
choices[].index | integer | 是 | 选项索引 示例：0。 |
choices[].message | object | 是 | — |
choices[].message.role | string | 是 | 示例：assistant。 |
choices[].message.content | string | 是 | 消息内容 |
choices[].finish_reason | string | 是 | 完成完成的原因 示例：stop。 |
usage | object | 否 | — |
usage.prompt_tokens | integer | 是 | 提示中的 token 数量 示例：10。 |
usage.completion_tokens | integer | 是 | 完成中的 token 数量 示例：50。 |
usage.total_tokens | integer | 是 | 总 token 数量 示例：60。 |
json
{
"id": "chatcmpl-example-123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-5-2",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A serene mountain landscape at sunrise"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 50,
"total_tokens": 60
}
}400 — 错误请求 - 无效的请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | object | 否 | — |
error.message | string | 否 | 示例：无效的请求参数。 |
error.type | string | 否 | 示例：invalid_request_error。 |
json
{
"error": {
"message": "无效的请求参数",
"type": "invalid_request_error"
}
}401 — 未授权 - 无效或缺少 API key
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | object | 否 | — |
error.message | string | 否 | 示例：未授权。 |
error.type | string | 否 | 示例：authentication_error。 |
json
{
"error": {
"message": "未授权",
"type": "authentication_error"
}
}429 — 速率限制 - 请求过多
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | object | 否 | — |
error.message | string | 否 | 示例：超出速率限制。 |
error.type | string | 否 | 示例：rate_limit_error。 |
json
{
"error": {
"message": "超出速率限制",
"type": "rate_limit_error"
}
}