GPT 5.2

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /gpt-5-2/v1/chat/completions

Full URL: https://ai.modelfold.online/gpt-5-2/v1/chat/completions

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

WARNING

⚠️ Chat only

This model currently supports chat requests only and has not yet been adapted for agent use. Connecting it to an agent may cause request errors or unexpected results.

GPT-5-2 API is a next-generation multimodal model with exceptional reasoning capabilities, supporting text and image inputs with Web Search grounding and adjustable reasoning effort.

Multimodal — Supports text and image inputs
Real-time Search — Web search grounding enabled
Reasoning Effort — Adjustable reasoning effort level
Flexible Roles — Multiple message roles supported

Unified Media File Format

::: caution In the messages parameter's content array, only images are supported. All image files use the same format structure:

The type field is always "image_url"
The image_url field name remains unchanged
The only thing that changes is the url value, which points to the corresponding image address

For example: { type: 'image_url', image_url: { url: '...' } } structure.

:::

Tools Parameter

The tools parameter is an optional array that allows you to enable Web Search grounding.

Web Search

Use this format to enable Web Search grounding:

json

{
  "type": "function",
  "function": {
    "name": "web_search"
  }
}

This enables real-time information retrieval via Web Search.

Response Example

json

{
  "id": "chatcmpl-example-123",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-5-2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "hello,can i help you?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60
  }
}

Error handling

Check the response body, not only the HTTP status. Errors are returned either as {"code": ..., "msg": "..."} (for example 401 invalid API key, 402 insufficient credits, 429 rate limited; the HTTP status may still be 200) or as {"error": {"type": "...", "message": "..."}}.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`messages`	`array<object>`	Yes	An array of message objects. Each message has a role and content. Unified Media File Format: In the content array, only images are supported. All image files use the same format structure: - The `type` field is always `"image_url"` - The `image_url` field name remains unchanged - The only thing that changes is the `url` value, which points to the corresponding image address For example: `{ type: 'image_url', image_url: { url: '...' } }` structure.
`messages[].role`	`string`	Yes	Message role - developer: Developer-provided instructions that the model should follow, regardless of user messages. In o1 models and newer versions, developer messages replace the previous system messages. - system: Developer-provided instructions that the model should follow, regardless of user messages. In o1 models and newer versions, please use developer messages instead. - user: Messages sent by end users, containing prompts or additional context information. - assistant: Messages sent by the model in response to user messages. Allowed values：`developer` / `system` / `user` / `assistant`。示例：`developer`。
`messages[].content`	`array<object	object>`	Yes
`tools`	`array<object>`	No	An optional array of tools the model may call. Supports Web Search: `{"type": "function", "function": {"name": "web_search"}}` - Enables real-time information retrieval via Web Search.
`tools[].type`	`string`	Yes	Must be `function`. Allowed values：`function`。示例：`function`。
`tools[].function`	`object`	Yes	—
`tools[].function.name`	`string`	Yes	Must be `web_search`. Allowed values：`web_search`。示例：`web_search`。
`reasoning_effort`	`string`	No	The effort level for the model to use for reasoning. Low effort is faster to respond, high effort is slower to respond but solves more complex problems. Default is "high". Default：`"high"`。 Allowed values：`low` / `high`。示例：`high`。

Request Example

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"
}

Response

200 — Request successful. Returns the standard chat completion format.

参数	类型	必填	说明
`id`	`string`	否	Unique identifier for the chat completion 示例：`chatcmpl-example-123`。
`object`	`string`	否	Object type 示例：`chat.completion`。
`created`	`integer`	否	Unix timestamp of when the completion was created 示例：`1677652288`。
`model`	`string`	否	Model name 示例：`gpt-5-2`。
`choices`	`array<object>`	否	Array of completion choices
`choices[].index`	`integer`	是	Index of the choice 示例：`0`。
`choices[].message`	`object`	是	—
`choices[].message.role`	`string`	是	示例：`assistant`。
`choices[].message.content`	`string`	是	Message content
`choices[].finish_reason`	`string`	是	Reason why the completion finished 示例：`stop`。
`usage`	`object`	否	—
`usage.prompt_tokens`	`integer`	是	Number of tokens in the prompt 示例：`10`。
`usage.completion_tokens`	`integer`	是	Number of tokens in the completion 示例：`50`。
`usage.total_tokens`	`integer`	是	Total number of tokens 示例：`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 — Bad Request - Invalid request parameters

参数	类型	必填	说明
`error`	`object`	否	—
`error.message`	`string`	否	示例：`Invalid request parameters`。
`error.type`	`string`	否	示例：`invalid_request_error`。

json

{
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

401 — Unauthorized - Invalid or missing API key

参数	类型	必填	说明
`error`	`object`	否	—
`error.message`	`string`	否	示例：`Unauthorized`。
`error.type`	`string`	否	示例：`authentication_error`。

json

{
  "error": {
    "message": "Unauthorized",
    "type": "authentication_error"
  }
}

429 — Rate Limited - Too many requests

参数	类型	必填	说明
`error`	`object`	否	—
`error.message`	`string`	否	示例：`Rate limit exceeded`。
`error.type`	`string`	否	示例：`rate_limit_error`。

json

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

GPT 5.2 ​

Endpoint ​

Unified Media File Format ​

Tools Parameter ​

Web Search ​

Response Example ​

Error handling ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful. Returns the standard chat completion format. ​

400 — Bad Request - Invalid request parameters ​

401 — Unauthorized - Invalid or missing API key ​

429 — Rate Limited - Too many requests ​

500 — Server error. ​

GPT 5.2

Endpoint

Unified Media File Format

Tools Parameter

Web Search

Response Example

Error handling

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful. Returns the standard chat completion format.

400 — Bad Request - Invalid request parameters

401 — Unauthorized - Invalid or missing API key

429 — Rate Limited - Too many requests

500 — Server error.