> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 多模态响应接口

>  - 完全兼容 OpenAI Responses API 格式
- 支持文本和图像的多模态输入
- 支持工具扩展：网络搜索、文件搜索、函数调用、远程MCP 

```bash cURL theme={null}
curl https://api.apimart.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "model": "gpt-5.2-pro",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "这张图片里有什么？"
          },
          {
            "type": "input_image",
            "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
          }
        ]
      }
    ]
  }'
```

```python Python theme={null}
import requests
import os

url = "https://api.apimart.ai/v1/responses"

payload = {
    "model": "gpt-5.2-pro",
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "这张图片里有什么？"
                },
                {
                    "type": "input_image",
                    "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
                }
            ]
        }
    ]
}

headers = {
    "Authorization": f"Bearer {os.environ.get('OPENAI_API_KEY')}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/responses";

const payload = {
  model: "gpt-5.2-pro",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "这张图片里有什么？"
        },
        {
          type: "input_image",
          image_url: "https://openai-documentation.vercel.app/images/cat_and_otter.png"
        }
      ]
    }
  ]
};

const headers = {
  "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"
)

func main() {
    url := "https://api.apimart.ai/v1/responses"

    payload := map[string]interface{}{
        "model": "gpt-5.2-pro",
        "input": []map[string]interface{}{
            {
                "role": "user",
                "content": []map[string]string{
                    {
                        "type": "input_text",
                        "text": "这张图片里有什么？",
                    },
                    {
                        "type":      "input_image",
                        "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",
                    },
                },
            },
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENAI_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={null}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.apimart.ai/v1/responses";
        String apiKey = System.getenv("OPENAI_API_KEY");

        String payload = """
        {
          "model": "gpt-5.2-pro",
          "input": [
            {
              "role": "user",
              "content": [
                {
                  "type": "input_text",
                  "text": "这张图片里有什么？"
                },
                {
                  "type": "input_image",
                  "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
                }
              ]
            }
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
```

```php PHP theme={null}
<?php

$url = "https://api.apimart.ai/v1/responses";
$apiKey = getenv('OPENAI_API_KEY');

$payload = [
    "model" => "gpt-5.2-pro",
    "input" => [
        [
            "role" => "user",
            "content" => [
                [
                    "type" => "input_text",
                    "text" => "这张图片里有什么？"
                ],
                [
                    "type" => "input_image",
                    "image_url" => "https://openai-documentation.vercel.app/images/cat_and_otter.png"
                ]
            ]
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $apiKey,
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

```ruby Ruby theme={null}
require 'net/http'
require 'json'
require 'uri'

url = URI("https://api.apimart.ai/v1/responses")
api_key = ENV['OPENAI_API_KEY']

payload = {
  model: "gpt-5.2-pro",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "这张图片里有什么？"
        },
        {
          type: "input_image",
          image_url: "https://openai-documentation.vercel.app/images/cat_and_otter.png"
        }
      ]
    }
  ]
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer #{api_key}"
request["Content-Type"] = "application/json"
request.body = payload.to_json

response = http.request(request)
puts response.body
```

```swift Swift theme={null}
import Foundation

let url = URL(string: "https://api.apimart.ai/v1/responses")!
let apiKey = ProcessInfo.processInfo.environment["OPENAI_API_KEY"] ?? ""

let payload: [String: Any] = [
    "model": "gpt-5.2-pro",
    "input": [
        [
            "role": "user",
            "content": [
                [
                    "type": "input_text",
                    "text": "这张图片里有什么？"
                ],
                [
                    "type": "input_image",
                    "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
                ]
            ]
        ]
    ]
]

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }
    
    if let data = data, let responseString = String(data: data, encoding: .utf8) {
        print(responseString)
    }
}

task.resume()
```

```csharp C# theme={null}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://api.apimart.ai/v1/responses";
        var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");

        var payload = @"{
            ""model"": ""gpt-5.2-pro"",
            ""input"": [
                {
                    ""role"": ""user"",
                    ""content"": [
                        {
                            ""type"": ""input_text"",
                            ""text"": ""这张图片里有什么？""
                        },
                        {
                            ""type"": ""input_image"",
                            ""image_url"": ""https://openai-documentation.vercel.app/images/cat_and_otter.png""
                        }
                    ]
                }
            ]
        }";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

        var content = new StringContent(payload, Encoding.UTF8, "application/json");
        var response = await client.PostAsync(url, content);
        var result = await response.Content.ReadAsStringAsync();

        Console.WriteLine(result);
    }
}
```

```c C theme={null}
#include <stdio.h>
#include <curl/curl.h>
#include <stdlib.h>

int main(void) {
    CURL *curl;
    CURLcode res;
    const char *api_key = getenv("OPENAI_API_KEY");

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if(curl) {
        const char *url = "https://api.apimart.ai/v1/responses";
        const char *payload = "{"
            "\"model\":\"gpt-5.2-pro\","
            "\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"这张图片里有什么？\"},{\"type\":\"input_image\",\"image_url\":\"https://openai-documentation.vercel.app/images/cat_and_otter.png\"}]}]"
        "}";

        char auth_header[256];
        snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", api_key);

        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, auth_header);
        headers = curl_slist_append(headers, "Content-Type: application/json");

        curl_easy_setopt(curl, CURLOPT_URL, url);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

        res = curl_easy_perform(curl);

        if(res != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed: %s\n",
                    curl_easy_strerror(res));
        }

        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }

    curl_global_cleanup();
    return 0;
}
```

```objectivec Objective-C theme={null}
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        NSURL *url = [NSURL URLWithString:@"https://api.apimart.ai/v1/responses"];
        NSString *apiKey = [NSProcessInfo processInfo].environment[@"OPENAI_API_KEY"];
        
        NSDictionary *payload = @{
            @"model": @"gpt-5.2-pro",
            @"input": @[
                @{
                    @"role": @"user",
                    @"content": @[
                        @{
                            @"type": @"input_text",
                            @"text": @"这张图片里有什么？"
                        },
                        @{
                            @"type": @"input_image",
                            @"image_url": @"https://openai-documentation.vercel.app/images/cat_and_otter.png"
                        }
                    ]
                }
            ]
        };
        
        NSError *error;
        NSData *jsonData = [NSJSONSerialization dataWithJSONObject:payload
                                                          options:0
                                                            error:&error];
        
        NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
        [request setHTTPMethod:@"POST"];
        [request setValue:[NSString stringWithFormat:@"Bearer %@", apiKey] 
            forHTTPHeaderField:@"Authorization"];
        [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
        [request setHTTPBody:jsonData];
        
        NSURLSessionDataTask *task = [[NSURLSession sharedSession] 
            dataTaskWithRequest:request
            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                if (error) {
                    NSLog(@"Error: %@", error);
                    return;
                }
                NSString *result = [[NSString alloc] initWithData:data 
                                                        encoding:NSUTF8StringEncoding];
                NSLog(@"%@", result);
            }];
        
        [task resume];
        [[NSRunLoop mainRunLoop] run];
    }
    return 0;
}
```

```ocaml OCaml theme={null}
(* Requires cohttp and yojson libraries *)
open Lwt
open Cohttp
open Cohttp_lwt_unix

let url = "https://api.apimart.ai/v1/responses"
let api_key = Sys.getenv "OPENAI_API_KEY"

let payload = {|{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "这张图片里有什么？"
        },
        {
          "type": "input_image",
          "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
        }
      ]
    }
  ]
}|}

let () =
  let headers = Header.init ()
    |> fun h -> Header.add h "Authorization" ("Bearer " ^ api_key)
    |> fun h -> Header.add h "Content-Type" "application/json"
  in
  let body = Cohttp_lwt.Body.of_string payload in
  
  let response = Client.post ~headers ~body (Uri.of_string url) >>= fun (resp, body) ->
    body |> Cohttp_lwt.Body.to_string >|= fun body_str ->
    print_endline body_str
  in
  Lwt_main.run response
```

```dart Dart theme={null}
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;

void main() async {
  final url = Uri.parse('https://api.apimart.ai/v1/responses');
  final apiKey = Platform.environment['OPENAI_API_KEY'];
  
  final payload = {
    'model': 'gpt-5.2-pro',
    'input': [
      {
        'role': 'user',
        'content': [
          {
            'type': 'input_text',
            'text': '这张图片里有什么？'
          },
          {
            'type': 'input_image',
            'image_url': 'https://openai-documentation.vercel.app/images/cat_and_otter.png'
          }
        ]
      }
    ]
  };
  
  final response = await http.post(
    url,
    headers: {
      'Authorization': 'Bearer $apiKey',
      'Content-Type': 'application/json',
    },
    body: jsonEncode(payload),
  );
  
  print(response.body);
}
```

```r R theme={null}
library(httr)
library(jsonlite)

url <- "https://api.apimart.ai/v1/responses"
api_key <- Sys.getenv("OPENAI_API_KEY")

payload <- list(
  model = "gpt-5.2-pro",
  input = list(
    list(
      role = "user",
      content = list(
        list(
          type = "input_text",
          text = "这张图片里有什么？"
        ),
        list(
          type = "input_image",
          image_url = "https://openai-documentation.vercel.app/images/cat_and_otter.png"
        )
      )
    )
  )
)

response <- POST(
  url,
  add_headers(
    Authorization = paste("Bearer", api_key),
    `Content-Type` = "application/json"
  ),
  body = toJSON(payload, auto_unbox = TRUE),
  encode = "raw"
)

cat(content(response, "text"))
```

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "id": "resp-9876543210",
    "object": "response",
    "created": 1677652288,
    "model": "gpt-5.2-pro",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "这张图片中有一只猫和一只水獭。它们看起来正在互动，场景非常可爱和温馨。猫咪和水獭似乎相处得很融洽。"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 156,
      "completion_tokens": 45,
      "total_tokens": 201
    }
  }
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的API密钥",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}
```

```json 403 theme={null}
{
  "error": {
    "code": 403,
    "message": "访问被禁止，您没有权限访问此资源",
    "type": "permission_error"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}
```

```json 502 theme={null}
{
  "error": {
    "code": 502,
    "message": "网关错误，服务器暂时不可用",
    "type": "bad_gateway"
  }
}
```

## Authorizations

**Authorization** `string` *required*

所有接口均需要使用Bearer Token进行认证

获取 API Key：

访问 [API Key 管理页面](https://apimart.ai/keys) 获取您的 API Key

使用时在请求头中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: gpt-5.2-pro)

模型名称

支持的模型包括：

* `gpt-5.2-pro`
* `gpt-5.2-codex`
* `qwen3.8-max`
* 更多模型持续更新中...

**input** `array` *required*

输入内容列表

输入数组，每个输入项包含 `role` 和 `content` 两个字段。

**💡 快速填写（Try it 区域）：**

1. 点击 "+ Add an item" 添加一个输入项
2. `role` 输入：`user`（用户消息）、`assistant`（AI回复）或 `system`（系统提示词）
3. `content` 添加内容块（可包含文本和图像）

**详细字段说明**

**role** `string` *required* (default: user)

角色类型

可选值：`user`（用户消息）、`assistant`（AI回复，用于多轮对话）、`system`（系统提示词，设置AI行为）

**content** `array` *required*

内容数组

支持多种类型的内容块，可以包含文本和图像。

**内容块类型**

**type** `string` *required*

内容类型

可选值：

* `input_text`: 文本输入
* `input_image`: 图像输入

**text** `string`

文本内容

当 `type` 为 `input_text` 时使用，填写文本内容

**image\_url** `string`

图像URL

当 `type` 为 `input_image` 时使用

支持两种格式：

**1. 完整的图像URL地址**

* 公开可访问的图像URL（http\:// 或 https\://）
* 示例：`https://example.com/image.jpg`

**2. Base64 编码格式**

* **必须使用完整的 Data URI 格式**
* 格式：`data:image/{格式};base64,{base64数据}`
* 支持的图片格式：jpeg、png、gif、webp
* 示例：`data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`
* ⚠️ 注意：必须包含 `data:image/jpeg;base64,` 前缀部分

**temperature** `number`

控制输出随机性，范围 0-2

* 较低的值（如 0.2）使输出更确定
* 较高的值（如 1.8）使输出更随机

默认值：1.0

**max\_tokens** `integer`

生成的最大token数量

不同模型有不同的最大值限制，请参考具体模型文档

**stream** `boolean`

是否使用流式输出

* `true`: 流式返回（SSE格式）
* `false`: 一次性返回完整响应

默认值：false

**top\_p** `number`

核采样参数，范围 0-1

控制生成文本的多样性，建议与 temperature 二选一使用

默认值：1.0

**tools** `array`

工具列表，用于扩展模型能力

支持的工具类型：

* **网络搜索** (`web_search`): 实时搜索互联网信息
* **文件搜索** (`file_search`): 搜索已上传的文件内容
* **函数调用** (`function`): 调用自定义函数
* **远程MCP** (`remote_mcp`): 连接远程模型上下文协议服务

示例：`[{"type": "web_search"}]`

## Response

**id** `string`

响应的唯一标识符

**object** `string`

对象类型，固定为 `response`

**created** `integer`

创建时间戳

**model** `string`

实际使用的模型名称

**choices** `array`

生成的回复列表

**属性**

**index** `integer`

选项索引

**message** `object`

消息内容

**属性**

**role** `string`

角色类型（assistant）

**content** `string`

生成的文本内容

**finish\_reason** `string`

结束原因

可能的值：

* `stop` - 自然结束
* `length` - 达到最大长度
* `content_filter` - 内容过滤

**usage** `object`

token使用统计

**属性**

**prompt\_tokens** `integer`

输入内容的token数

**completion\_tokens** `integer`

生成内容的token数

**total\_tokens** `integer`

总token数

## 使用示例

### 纯文本输入

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "你好，介绍一下人工智能"
        }
      ]
    }
  ]
}
```

### 使用网络搜索工具

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [{"type": "web_search"}],
  "input": "今天有什么正面的新闻？"
}
```

```bash cURL示例 theme={null}
curl "https://api.apimart.ai/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
        "model": "gpt-5.2-pro",
        "tools": [{"type": "web_search"}],
        "input": "今天有什么正面的新闻？"
    }'
```

### 图像理解

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "描述这张图片"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image.jpg"
        }
      ]
    }
  ]
}
```

### 多图像分析

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "比较这两张图片的异同"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image1.jpg"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image2.jpg"
        }
      ]
    }
  ]
}
```

### Base64编码图像

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "分析这张图片"
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
        }
      ]
    }
  ]
}
```

### 使用文件搜索工具

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [{"type": "file_search"}],
  "input": "根据已上传的文档，总结公司的季度业绩"
}
```

### 使用函数调用

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，例如：北京"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "input": "北京今天天气怎么样？"
}
```

### 使用远程MCP

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [
    {
      "type": "remote_mcp",
      "remote_mcp": {
        "url": "https://mcp.example.com/api",
        "auth_token": "your_mcp_token"
      }
    }
  ],
  "input": "查询数据库中的用户信息"
}
```

### 组合使用多个工具

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [
    {"type": "web_search"},
    {"type": "file_search"},
    {
      "type": "function",
      "function": {
        "name": "calculate",
        "description": "执行数学计算",
        "parameters": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "数学表达式"
            }
          },
          "required": ["expression"]
        }
      }
    }
  ],
  "input": "搜索最新的比特币价格，并计算100个比特币的总价值"
}
```

## 内容类型说明

### input\_text

文本输入类型

**属性：**

* `type`: 固定为 `"input_text"`
* `text`: 文本内容（字符串）

### input\_image

图像输入类型

**属性：**

* `type`: 固定为 `"input_image"`
* `image_url`: 图像URL或Base64编码的数据URI

**支持两种格式：**

1. **完整的图像URL地址**
   * 公开可访问的图像URL（http\:// 或 https\://）
   * 示例：`https://example.com/image.jpg`

2. **Base64 编码格式**
   * **必须使用完整的 Data URI 格式**
   * 格式：`data:image/{格式};base64,{base64数据}`
   * 示例：`data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`
   * ⚠️ 注意：必须包含 `data:image/jpeg;base64,` 前缀部分（其中 `jpeg` 可以替换为 `png`、`gif`、`webp` 等）

**支持的图像格式：**

* JPEG
* PNG
* GIF
* WebP

**图像大小限制：**

* 最大文件大小：20MB
* 推荐分辨率：不超过2048x2048像素

## 工具使用详解

### 网络搜索 (Web Search)

使用网络搜索工具可以让模型访问实时互联网信息。

**配置示例：**

```json theme={null}
{
  "tools": [{"type": "web_search"}]
}
```

**适用场景：**

* 查询最新新闻和时事
* 获取实时数据（股票、天气、汇率等）
* 搜索最新的技术文档和资料
* 验证事实信息

### 文件搜索 (File Search)

文件搜索工具允许模型在已上传的文档中搜索相关信息。

**配置示例：**

```json theme={null}
{
  "tools": [{"type": "file_search"}]
}
```

**适用场景：**

* 分析企业内部文档
* 搜索技术规范和手册
* 查询合同和法律文件
* 知识库问答系统

### 函数调用 (Function Calling)

定义自定义函数，让模型能够调用外部API或执行特定操作。

**完整配置示例：**

```json theme={null}
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "获取股票的实时价格",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "股票代码，例如：AAPL"
            },
            "currency": {
              "type": "string",
              "enum": ["USD", "CNY"],
              "description": "货币单位",
              "default": "USD"
            }
          },
          "required": ["symbol"]
        }
      }
    }
  ]
}
```

**参数说明：**

* `name`: 函数名称（必需）
* `description`: 函数功能描述（必需）
* `parameters`: 参数定义，使用JSON Schema格式
  * `type`: 参数类型
  * `properties`: 参数属性定义
  * `required`: 必需参数列表

**适用场景：**

* 调用第三方API
* 执行数据库查询
* 触发业务流程
* 与内部系统集成

### 远程MCP (Remote MCP)

连接到远程模型上下文协议（MCP）服务，扩展模型能力。

**配置示例：**

```json theme={null}
{
  "tools": [
    {
      "type": "remote_mcp",
      "remote_mcp": {
        "url": "https://your-mcp-server.com/api",
        "auth_token": "your_auth_token",
        "timeout": 30
      }
    }
  ]
}
```

**参数说明：**

* `url`: MCP服务器地址（必需）
* `auth_token`: 认证令牌（可选）
* `timeout`: 超时时间（秒），默认30秒

**适用场景：**

* 连接企业级AI服务
* 使用专业领域模型
* 访问受保护的数据源
* 分布式AI系统集成

## 工具响应格式

当模型使用工具时，响应格式会包含工具调用信息：

```json theme={null}
{
  "id": "resp-123456",
  "object": "response",
  "created": 1677652288,
  "model": "gpt-5.2-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"北京\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

**工具调用流程：**

1. 模型接收用户输入
2. 分析是否需要使用工具
3. 如需要，返回工具调用请求
4. 客户端执行工具调用
5. 将工具结果返回给模型
6. 模型生成最终响应

## 注意事项

1. **图像URL要求**：
   * 必须是公开可访问的URL
   * 或使用Base64编码的Data URI格式

2. **Token计费**：
   * 图像会根据其分辨率消耗相应的tokens
   * 高分辨率图像会自动调整大小以优化成本
   * 工具调用也会消耗额外的tokens

3. **内容顺序**：
   * content数组中的元素顺序会影响模型理解
   * 建议先放置文本指令，再放置图像

4. **多模态组合**：
   * 可以在一个请求中混合多个文本和图像
   * 支持多轮对话，保持上下文连贯性

5. **工具使用限制**：
   * 同时使用多个工具时，模型会智能选择最合适的工具
   * 函数调用需要明确的函数定义和参数说明
   * 网络搜索结果可能受地域和时间限制

6. **API兼容性**：
   * 完全兼容OpenAI Responses API格式
   * 可无缝迁移现有OpenAI代码
   * 支持所有OpenAI工具扩展功能


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.