> ## 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 Multimodal Responses API

>  - Полная совместимость с форматом OpenAI Responses API
- Поддержка мультимодального ввода: текст и изображения
- Поддержка расширений-инструментов: веб-поиск, поиск по файлам, function calling, удалённый MCP 

<RequestExample>
  ```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": "What is in this image?"
            },
            {
              "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": "What is in this image?"
                  },
                  {
                      "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: "What is in this image?"
          },
          {
            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": "What is in this image?",
                      },
                      {
                          "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": "What is in this image?"
                  },
                  {
                    "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" => "What is in this image?"
                  ],
                  [
                      "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: "What is in this image?"
          },
          {
            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": "What is in this image?"
                  ],
                  [
                      "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"": ""What is in this image?""
                          },
                          {
                              ""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\":\"What is in this image?\"},{\"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": @"What is in this image?"
                          },
                          @{
                              @"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": "What is in this image?"
          },
          {
            "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': 'What is in this image?'
            },
            {
              '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 = "What is in this image?"
          ),
          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"))
  ```
</RequestExample>

<ResponseExample>
  ```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": "This image shows a cat and an otter. They appear to be interacting with each other in a very cute and heartwarming scene. The cat and otter seem to be getting along well."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 156,
        "completion_tokens": 45,
        "total_tokens": 201
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Invalid request parameters",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient account balance, please top up and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "Access forbidden, you do not have permission to access this resource",
      "type": "permission_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests, please try again later",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "Internal server error, please try again later",
      "type": "server_error"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": 502,
      "message": "Gateway error, server temporarily unavailable",
      "type": "bad_gateway"
    }
  }
  ```
</ResponseExample>

## Авторизация

<ParamField header="Authorization" type="string" required>
  \##Все API требуют аутентификации Bearer Token##

  Получение API-ключа:

  Откройте [страницу управления API-ключами](https://apimart.ai/keys), чтобы получить ваш API-ключ

  Добавьте в заголовок запроса:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required default="gpt-5.2-pro">
  Название модели

  Поддерживаемые модели:

  * `gpt-5.2-pro`
  * `gpt-5.2-codex`
  * Скоро будут добавлены новые модели...
</ParamField>

<ParamField body="input" type="array" required>
  Список входных данных

  Входной массив, каждый элемент содержит поля `role` и `content`.

  **💡 Быстрое заполнение (область «Try it»):**

  1. Нажмите «+ Add an item», чтобы добавить элемент ввода
  2. В поле `role` введите: `user` (сообщение пользователя), `assistant` (ответ AI) или `system` (системная подсказка)
  3. В поле `content` добавьте блоки контента (могут включать текст и изображения)

  <Expandable title="Описание полей">
    <ParamField body="role" type="string" required default="user">
      Тип роли

      Варианты: `user` (сообщение пользователя), `assistant` (ответ AI, для многошагового диалога), `system` (системная подсказка для задания поведения AI)
    </ParamField>

    <ParamField body="content" type="array" required>
      Массив контента

      Поддерживает различные типы блоков контента, может включать текст и изображения.

      <Expandable title="Типы блоков контента">
        <ParamField body="type" type="string" required>
          Тип контента

          Варианты:

          * `input_text`: текстовый ввод
          * `input_image`: ввод изображения
        </ParamField>

        <ParamField body="text" type="string">
          Текстовое содержимое

          Используется, когда `type` равен `input_text`; укажите текстовое содержимое
        </ParamField>

        <ParamField body="image_url" type="string">
          URL изображения

          Используется, когда `type` равен `input_image`; укажите URL изображения или Base64-кодировку

          Поддерживает два формата:

          **1. Полный URL изображения**

          * Публично доступный URL изображения (http\:// или https\://)
          * Пример: `https://example.com/image.jpg`

          **2. Формат Base64**

          * **Необходимо использовать полный формат Data URI**
          * Формат: `data:image/{format};base64,{base64_data}`
          * Поддерживаемые форматы изображений: jpeg, png, gif, webp
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="temperature" type="number">
  Управляет случайностью вывода, диапазон 0–2

  * Меньшие значения (например, 0.2) делают вывод более детерминированным
  * Большие значения (например, 1.8) делают вывод более случайным

  По умолчанию: 1.0
</ParamField>

<ParamField body="max_tokens" type="integer">
  Максимальное количество генерируемых токенов

  У разных моделей разные максимальные лимиты, обратитесь к документации конкретной модели
</ParamField>

<ParamField body="stream" type="boolean">
  Использовать ли потоковый вывод

  * `true`: потоковый ответ (формат SSE)
  * `false`: вернуть полный ответ за один раз

  По умолчанию: false
</ParamField>

<ParamField body="top_p" type="number">
  Параметр ядровой выборки (nucleus sampling), диапазон 0–1

  Управляет разнообразием генерируемого текста, рекомендуется использовать его как альтернативу temperature

  По умолчанию: 1.0
</ParamField>

<ParamField body="tools" type="array">
  Список инструментов для расширения возможностей модели

  Поддерживаемые типы инструментов:

  * **Веб-поиск** (`web_search`): поиск актуальной информации в интернете
  * **Поиск по файлам** (`file_search`): поиск по содержимому загруженных файлов
  * **Function Calling** (`function`): вызов пользовательских функций
  * **Удалённый MCP** (`remote_mcp`): подключение к удалённым сервисам Model Context Protocol

  Пример: `[{"type": "web_search"}]`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Уникальный идентификатор ответа
</ResponseField>

<ResponseField name="object" type="string">
  Тип объекта, фиксированное значение `response`
</ResponseField>

<ResponseField name="created" type="integer">
  Временная метка создания
</ResponseField>

<ResponseField name="model" type="string">
  Фактически использованное название модели
</ResponseField>

<ResponseField name="choices" type="array">
  Список сгенерированных ответов

  <Expandable title="Свойства">
    <ResponseField name="index" type="integer">
      Индекс варианта
    </ResponseField>

    <ResponseField name="message" type="object">
      Содержимое сообщения

      <Expandable title="Свойства">
        <ResponseField name="role" type="string">
          Тип роли (assistant)
        </ResponseField>

        <ResponseField name="content" type="string">
          Сгенерированный текстовый контент
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      Причина завершения

      Возможные значения:

      * `stop` — естественное завершение
      * `length` — достигнут максимальный размер
      * `content_filter` — фильтрация контента
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Статистика использования токенов

  <Expandable title="Свойства">
    <ResponseField name="prompt_tokens" type="integer">
      Количество входных токенов
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Количество выходных токенов
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Общее количество токенов
    </ResponseField>
  </Expandable>
</ResponseField>

## Примеры использования

### Только текстовый ввод

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Hello, introduce artificial intelligence"
        }
      ]
    }
  ]
}
```

### Использование инструмента веб-поиска

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [{"type": "web_search"}],
  "input": "What positive news is there today?"
}
```

```bash cURL Example 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": "What positive news is there today?"
    }'
```

### Понимание изображений

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Describe this image"
        },
        {
          "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": "Compare the similarities and differences of these two images"
        },
        {
          "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": "Analyze this image"
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
        }
      ]
    }
  ]
}
```

### Использование инструмента поиска по файлам

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [{"type": "file_search"}],
  "input": "Based on uploaded documents, summarize the company's quarterly performance"
}
```

### Использование Function Calling

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather information for a specified city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name, e.g.: Beijing"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature unit"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "input": "What's the weather like in Beijing today?"
}
```

### Использование удалённого 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": "Query user information in the database"
}
```

### Комбинирование нескольких инструментов

```json theme={null}
{
  "model": "gpt-5.2-pro",
  "tools": [
    {"type": "web_search"},
    {"type": "file_search"},
    {
      "type": "function",
      "function": {
        "name": "calculate",
        "description": "Perform mathematical calculations",
        "parameters": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "Mathematical expression"
            }
          },
          "required": ["expression"]
        }
      }
    }
  ],
  "input": "Search for the latest Bitcoin price and calculate the total value of 100 Bitcoins"
}
```

## Спецификации типов контента

### input\_text

Тип текстового ввода

**Свойства:**

* `type`: фиксированное значение `"input_text"`
* `text`: текстовое содержимое (строка)

### input\_image

Тип ввода изображения

**Свойства:**

* `type`: фиксированное значение `"input_image"`
* `image_url`: URL изображения или Base64-кодированный data URI

**Поддерживаемые форматы изображений:**

* JPEG
* PNG
* GIF
* WebP

**Ограничения размера изображения:**

* Максимальный размер файла: 20 МБ
* Рекомендуемое разрешение: не более 2048x2048 пикселей

## Подробности использования инструментов

### Веб-поиск

Инструмент веб-поиска позволяет модели получать актуальную информацию из интернета.

**Пример конфигурации:**

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

**Сценарии использования:**

* Запрос последних новостей и текущих событий
* Получение данных в реальном времени (акции, погода, курсы валют и т. д.)
* Поиск актуальной технической документации
* Проверка фактической информации

### Поиск по файлам

Инструмент поиска по файлам позволяет модели искать релевантную информацию в загруженных документах.

**Пример конфигурации:**

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

**Сценарии использования:**

* Анализ внутрикорпоративных документов
* Поиск по техническим спецификациям и руководствам
* Запросы по договорам и юридическим документам
* Системы вопросов и ответов на базе знаний

### Function Calling

Определение пользовательских функций позволяет модели вызывать внешние API или выполнять конкретные операции.

**Полный пример конфигурации:**

```json theme={null}
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "Get real-time stock price",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "Stock symbol, e.g.: AAPL"
            },
            "currency": {
              "type": "string",
              "enum": ["USD", "CNY"],
              "description": "Currency unit",
              "default": "USD"
            }
          },
          "required": ["symbol"]
        }
      }
    }
  ]
}
```

**Описание параметров:**

* `name`: имя функции (обязательно)
* `description`: описание функции (обязательно)
* `parameters`: определение параметров в формате JSON Schema
  * `type`: тип параметра
  * `properties`: определения свойств параметров
  * `required`: список обязательных параметров

**Сценарии использования:**

* Вызов сторонних API
* Выполнение запросов к базе данных
* Запуск бизнес-процессов
* Интеграция с внутренними системами

### Удалённый MCP

Подключение к удалённым сервисам Model Context Protocol (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\": \"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

**Рабочий процесс вызова инструмента:**

1. Модель получает пользовательский ввод
2. Анализирует, нужны ли инструменты
3. При необходимости возвращает запрос на вызов инструмента
4. Клиент выполняет вызов инструмента
5. Возвращает результаты инструмента модели
6. Модель формирует окончательный ответ

## Важные замечания

1. **Требования к URL изображений**:
   * Должен быть публично доступным URL
   * Или использовать формат Base64-кодированного Data URI

2. **Тарификация токенов**:
   * Изображения расходуют токены в зависимости от их разрешения
   * Изображения с высоким разрешением автоматически уменьшаются для оптимизации стоимости
   * Вызовы инструментов также потребляют дополнительные токены

3. **Порядок контента**:
   * Порядок элементов в массиве content влияет на понимание моделью
   * Рекомендуется сначала располагать текстовые инструкции, затем изображения

4. **Мультимодальные комбинации**:
   * В одном запросе можно смешивать несколько текстов и изображений
   * Поддерживаются многошаговые диалоги с сохранением контекста

5. **Ограничения использования инструментов**:
   * При одновременном использовании нескольких инструментов модель интеллектуально выбирает наиболее подходящий
   * Function calling требует чёткого определения функций и описания параметров
   * Результаты веб-поиска могут быть ограничены регионом и временем

6. **Совместимость API**:
   * Полная совместимость с форматом OpenAI Responses API
   * Бесшовная миграция существующего кода OpenAI
   * Поддержка всех функций расширения инструментов OpenAI