Запрос чату

POST

chat

completions

Создать chat completion

curl --request POST \
  --url https://speshu.ai/api/v1/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Ты полезный ассистент"
    },
    {
      "role": "user",
      "content": "Привет! Как дела?"
    }
  ],
  "prompt": "Напиши стихотворение про кота",
  "max_tokens": 1000,
  "max_completion_tokens": 1000,
  "temperature": 1,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "response_format": {},
  "provider": {
    "allow_fallbacks": true,
    "order": [
      "OpenAI",
      "Anthropic"
    ],
    "only": [
      "OpenAI",
      "Google"
    ],
    "ignore": [
      "DeepInfra"
    ],
    "sort": "price",
    "max_price": {
      "prompt": 10,
      "completion": 20,
      "image": 5,
      "audio": 15,
      "request": 1
    }
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить текущую погоду для указанного местоположения",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Название города"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ]
        },
        "strict": false
      }
    }
  ],
  "tool_choice": "auto",
  "reasoning": {
    "effort": "medium",
    "summary": "auto",
    "enabled": true,
    "max_tokens": 2000,
    "exclude": false
  },
  "plugins": "<array>",
  "web_search_options": {
    "search_context_size": "medium"
  },
  "user": "user-123",
  "stop": [
    "\n"
  ],
  "seed": 42,
  "n": 1,
  "stream": false,
  "logprobs": false,
  "top_logprobs": 5,
  "logit_bias": {
    "50256": -100
  },
  "parallel_tool_calls": true,
  "image_config": {
    "quality": "high",
    "size": 512
  },
  "modalities": [
    "text",
    "audio"
  ],
  "audio": {
    "voice": "alloy",
    "format": "pcm16"
  }
}
'

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Я хорошо, спасибо что спросили. Чем могу помочь?",
        "name": "Ассистент",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Moscow\"}"
            }
          }
        ],
        "refusal": null,
        "reasoning": null,
        "audio": {
          "id": "<string>",
          "data": "<string>",
          "transcript": "<string>",
          "expires_at": 123
        },
        "annotations": [
          {}
        ]
      },
      "finish_reason": "stop",
      "reasoning_details": "<array>",
      "logprobs": {
        "content": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "system_fingerprint": "fp_29330a9688",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60,
    "completion_tokens_details": {
      "reasoning_tokens": 100,
      "audio_tokens": 0,
      "image_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0,
      "video_tokens": 0
    },
    "server_tool_use": {
      "web_search_requests": 1
    },
    "cost_rub": 0.04131306,
    "cost": 0.04131306,
    "plugins": {
      "masker": {
        "operations": [
          {
            "operation": "mask",
            "latency_ms": 15,
            "cost_rub": 0.001
          },
          {
            "operation": "unmask",
            "latency_ms": 8,
            "cost_rub": 0
          }
        ],
        "total_cost_rub": 0.001
      }
    },
    "plugin_post_process_error": true
  }
}

Поддерживает текстовые диалоги, мультимодальные запросы (текст + изображения + аудио + видео + файлы), вызов функций и потоковую передачу.

Возможности

Агрегация провайдеров — автоматический выбор оптимального провайдера
Биллинг в рублях — точный учет стоимости
Reasoning Tokens — поддержка моделей с рассуждениями
Streaming — потоковая передача через SSE
Tool Calling — вызов внешних функций
Мультимодальность — обработка текста, изображений, аудио, видео и файлов

Параметры запроса

Обязательные

Параметр	Тип	Описание
`model`	string	ID модели из списка моделей

Контент

Параметр	Тип	Описание
`messages`	array	Массив сообщений диалога (рекомендуется)
`prompt`	string	Простой текстовый промпт (альтернатива messages)

Параметры генерации

Параметр	Тип	По умолчанию	Описание
`max_tokens`	integer	Без лимита	Максимум токенов в ответе
`max_completion_tokens`	integer	Без лимита	Альтернатива max_tokens
`temperature`	float (0-2)	1.0	Температура (0=детерминированный, 2=креативный)
`top_p`	float (0-1)	1.0	Nucleus sampling
`top_k`	integer	—	Top-K sampling
`frequency_penalty`	float (-2..2)	0	Штраф за повторение слов
`presence_penalty`	float (-2..2)	0	Штраф за повторение токенов
`stop`	string/array	—	Стоп-последовательности
`seed`	integer	—	Seed для воспроизводимости

Специальные возможности

Параметр	Тип	Описание
`stream`	boolean	Включить streaming (SSE)
`reasoning`	object	Настройки reasoning tokens
`tools`	array	Доступные функции для вызова
`tool_choice`	string/object	Выбор инструмента: “none”, “auto”, “required”
`response_format`	object	Формат ответа: text, json_object, json_schema, grammar
`web_search_options`	object	Встроенный веб-поиск
`provider`	object	Конфигурация роутинга по провайдерам
`plugins`	array	Подключение плагинов
`modalities`	array	Выходные модальности: “text”, “image”, “audio”
`audio`	object	Конфигурация аудио-вывода (voice, format)
`user`	string	Идентификатор конечного пользователя

Структура сообщений

Базовый формат

{
  "role": "user|assistant|system|developer|tool",
  "content": "Текст сообщения"
}

Мультимодальные сообщения

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Что на этом изображении?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
  ]
}

Другие типы контента

// Аудио вход
{"type": "input_audio", "input_audio": {"data": "base64...", "format": "mp3"}}

// Видео вход
{"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}

// Файл
{"type": "file", "file": {"filename": "doc.pdf", "file_data": "data:application/pdf;base64,..."}}

Системные сообщения с кешированием

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Длинная системная инструкция...",
      "cache_control": {"type": "ephemeral"}
    }
  ]
}

Примеры

curl -X POST "https://speshu.ai/api/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.5",
"messages": [{"role": "user", "content": "Привет!"}]
}'

Ответ

Успешный ответ (200)

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-5.5",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Текст ответа"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175,
    "cost_rub": 0.04131306,
    "cost": 0.04131306,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

Streaming (SSE)

При stream: true ответ приходит в формате Server-Sent Events:

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-5.5","choices":[{"index":0,"delta":{"role":"assistant","content":"Привет"}}]}

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-5.5","choices":[{"index":0,"delta":{"content":" мир"}}]}

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-5.5","choices":[],"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30,"cost_rub":0.015,"cost":0.015}}

data: [DONE]

Tool Calling

Определение функций

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить текущую погоду",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

Ответ модели с вызовом функции

{
  "tool_calls": [{
    "id": "call_123",
    "function": {"name": "get_weather", "arguments": "{\"city\": \"Москва\"}"}
  }]
}

Response Format

JSON Schema (структурированный вывод)

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "my_schema",
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        }
      },
      "strict": true
    }
  }
}

Поддерживаемые типы: text, json_object, json_schema, grammar (GBNF).

Reasoning Tokens

Для моделей с рассуждениями (o1, o3, DeepSeek-R1 и другие):

{
  "model": "openai/o1-preview",
  "messages": [{"role": "user", "content": "Реши: 2x + 5 = 13"}],
  "reasoning": {
    "effort": "high",
    "max_tokens": 1000
  }
}

Параметры reasoning

Параметр	Тип	Описание
`effort`	string	Уровень усилий: xhigh, high, medium, low, minimal, none
`max_tokens`	integer	Максимум токенов на рассуждения
`summary`	string	Детализация: auto, concise, detailed
`enabled`	boolean	Включить/выключить рассуждения
`exclude`	boolean	Скрыть рассуждения из ответа

Авторизации

Authorization

string

header

обязательно

API ключ передаётся в заголовке: Authorization: Bearer <SPESHU_AI_API_KEY>

Тело

application/json

model

string

обязательно

Идентификатор модели для использования

Пример:

"openai/gpt-4o"

messages

object[]

обязательно

Массив сообщений для отправки модели (обязателен если не указан prompt)

Show child attributes

Пример:

[
  {
    "role": "system",
    "content": "Ты полезный ассистент"
  },
  {
    "role": "user",
    "content": "Привет! Как дела?"
  }
]

prompt

string

Текстовый промпт (альтернатива messages). Если указан, будет преобразован в messages с role=user

Пример:

"Напиши стихотворение про кота"

max_tokens

number

Максимальное количество токенов для генерации

Требуемый диапазон: x >= 1

Пример:

1000

max_completion_tokens

number

Максимальное количество токенов для completion (альтернатива max_tokens)

Требуемый диапазон: x >= 1

Пример:

1000

temperature

number

Температура сэмплинга (0-2). Более высокие значения делают вывод более случайным

Требуемый диапазон: 0 <= x <= 2

Пример:

1

top_p

number

Nucleus sampling: вероятностная масса для рассмотрения (0-1)

Требуемый диапазон: 0 <= x <= 1

Пример:

1

frequency_penalty

number

Штраф за частоту использования токенов (-2 до 2)

Требуемый диапазон: -2 <= x <= 2

Пример:

0

presence_penalty

number

Штраф за присутствие токенов (-2 до 2)

Требуемый диапазон: -2 <= x <= 2

Пример:

0

response_format

object

Формат ответа модели

provider

object

Настройки провайдера для роутинга и фильтрации

Show child attributes

tools

object[]

Определения инструментов (tools) для function calling

Show child attributes

tool_choice

object

Выбор инструмента: none, auto, required или named function

Пример:

"auto"

reasoning

object

Настройки reasoning для reasoning моделей

Show child attributes

plugins

array

Плагины для расширения функциональности

web_search_options

object

Настройки встроенного веб-поиска (для моделей с нативной поддержкой)

Show child attributes

user

string

Уникальный идентификатор конечного пользователя для отслеживания и предотвращения злоупотреблений

Пример:

"user-123"

stop

Последовательности, при которых модель прекращает генерацию

Пример:

["\n"]

seed

number

Seed для детерминированной генерации (best-effort)

Пример:

42

number

Количество вариантов ответа (1-10)

Требуемый диапазон: 1 <= x <= 10

Пример:

1

stream

boolean

Включить потоковую передачу ответа

Пример:

false

logprobs

boolean

Возвращать log probabilities для output токенов

Пример:

false

top_logprobs

number

Количество наиболее вероятных токенов для возврата (0-20). Требует logprobs: true

Требуемый диапазон: 0 <= x <= 20

Пример:

5

logit_bias

object

Смещение вероятностей токенов по их ID (-100 до 100)

Пример:

{ "50256": -100 }

parallel_tool_calls

boolean

Разрешить параллельный вызов нескольких tools

Пример:

true

image_config

object

Настройки обработки изображений

Пример:

{ "quality": "high", "size": 512 }

modalities

enum<string>[]

Типы вывода модели

Доступные опции:

text,

image,

audio

Пример:

["text", "audio"]

audio

object

Настройки аудио выхода для моделей с поддержкой аудио (gpt-audio и др.)

Show child attributes

Ответ

string

обязательно

Уникальный идентификатор генерации

Пример:

"gen_581761234567890123"

object

string

обязательно

Тип объекта

Пример:

"chat.completion"

created

number

обязательно

Временная метка создания (Unix timestamp)

Пример:

1703001234

model

string

обязательно

ID модели, которая сгенерировала ответ

Пример:

"openai/gpt-4o"

choices

object[]

обязательно

Массив вариантов ответа

Show child attributes

system_fingerprint

string

System fingerprint от провайдера

Пример:

"fp_29330a9688"

usage

object

Информация об использовании токенов

Show child attributes

Список моделей

Создать chat completion

curl --request POST \
  --url https://speshu.ai/api/v1/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Ты полезный ассистент"
    },
    {
      "role": "user",
      "content": "Привет! Как дела?"
    }
  ],
  "prompt": "Напиши стихотворение про кота",
  "max_tokens": 1000,
  "max_completion_tokens": 1000,
  "temperature": 1,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "response_format": {},
  "provider": {
    "allow_fallbacks": true,
    "order": [
      "OpenAI",
      "Anthropic"
    ],
    "only": [
      "OpenAI",
      "Google"
    ],
    "ignore": [
      "DeepInfra"
    ],
    "sort": "price",
    "max_price": {
      "prompt": 10,
      "completion": 20,
      "image": 5,
      "audio": 15,
      "request": 1
    }
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить текущую погоду для указанного местоположения",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Название города"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ]
        },
        "strict": false
      }
    }
  ],
  "tool_choice": "auto",
  "reasoning": {
    "effort": "medium",
    "summary": "auto",
    "enabled": true,
    "max_tokens": 2000,
    "exclude": false
  },
  "plugins": "<array>",
  "web_search_options": {
    "search_context_size": "medium"
  },
  "user": "user-123",
  "stop": [
    "\n"
  ],
  "seed": 42,
  "n": 1,
  "stream": false,
  "logprobs": false,
  "top_logprobs": 5,
  "logit_bias": {
    "50256": -100
  },
  "parallel_tool_calls": true,
  "image_config": {
    "quality": "high",
    "size": 512
  },
  "modalities": [
    "text",
    "audio"
  ],
  "audio": {
    "voice": "alloy",
    "format": "pcm16"
  }
}
'

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Я хорошо, спасибо что спросили. Чем могу помочь?",
        "name": "Ассистент",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Moscow\"}"
            }
          }
        ],
        "refusal": null,
        "reasoning": null,
        "audio": {
          "id": "<string>",
          "data": "<string>",
          "transcript": "<string>",
          "expires_at": 123
        },
        "annotations": [
          {}
        ]
      },
      "finish_reason": "stop",
      "reasoning_details": "<array>",
      "logprobs": {
        "content": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "system_fingerprint": "fp_29330a9688",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60,
    "completion_tokens_details": {
      "reasoning_tokens": 100,
      "audio_tokens": 0,
      "image_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0,
      "video_tokens": 0
    },
    "server_tool_use": {
      "web_search_requests": 1
    },
    "cost_rub": 0.04131306,
    "cost": 0.04131306,
    "plugins": {
      "masker": {
        "operations": [
          {
            "operation": "mask",
            "latency_ms": 15,
            "cost_rub": 0.001
          },
          {
            "operation": "unmask",
            "latency_ms": 8,
            "cost_rub": 0
          }
        ],
        "total_cost_rub": 0.001
      }
    },
    "plugin_post_process_error": true
  }
}

Текстовая генерация

Модели

Другое

Возможности

Параметры запроса

Обязательные

Контент

Параметры генерации

Специальные возможности

Структура сообщений

Базовый формат

Мультимодальные сообщения

Другие типы контента

Системные сообщения с кешированием

Примеры

Ответ

Успешный ответ (200)

Streaming (SSE)

Tool Calling

Определение функций

Ответ модели с вызовом функции

Response Format

JSON Schema (структурированный вывод)

Reasoning Tokens

Параметры reasoning

Авторизации

Тело

Ответ

Текстовая генерация

Модели

Другое

Documentation Index

​Возможности

​Параметры запроса

​Обязательные

​Контент

​Параметры генерации

​Специальные возможности

​Структура сообщений

​Базовый формат

​Мультимодальные сообщения

​Другие типы контента

​Системные сообщения с кешированием

​Примеры

​Ответ

​Успешный ответ (200)

​Streaming (SSE)

​Tool Calling

​Определение функций

​Ответ модели с вызовом функции

​Response Format

​JSON Schema (структурированный вывод)

​Reasoning Tokens

​Параметры reasoning

Авторизации

Тело

Ответ

Возможности

Параметры запроса

Обязательные

Контент

Параметры генерации

Специальные возможности

Структура сообщений

Базовый формат

Мультимодальные сообщения

Другие типы контента

Системные сообщения с кешированием

Примеры

Ответ

Успешный ответ (200)

Streaming (SSE)

Tool Calling

Определение функций

Ответ модели с вызовом функции

Response Format

JSON Schema (структурированный вывод)

Reasoning Tokens

Параметры reasoning