Как работать с текстом

Практическая сторона POST /api/v1/chat/completions: как устроены сообщения, что можно положить в content, как получить предсказуемый JSON и какие параметры действительно влияют на результат. Сводная таблица всех полей запроса — в справочнике эндпоинта.

В примерах ниже $TEXT_MODEL — переменная окружения с идентификатором модели из GET /api/v1/models. Идентификаторы не зашивают в код: состав каталога меняется, а зашитый список устаревает молча. Разбор — в разделе Модели и цены.

Роли и порядок

Массив messages — это история диалога целиком, а не только последняя реплика. Каждый запрос повторно отправляет всю переписку, и провайдер берёт за неё плату — поэтому историю стоит обрезать, а не копить.

Роль	Кто пишет	Содержимое
`system`	Вы	Правила поведения модели
`developer`	Вы	Аналог `system`; часть провайдеров принимает только его
`user`	Пользователь	Вопрос или мультимодальный блок
`assistant`	Модель	Предыдущий ответ, включая `tool_calls`
`tool`	Ваш код	Результат выполнения функции

Порядок соблюдайте строго: system → история → последний user. В tool-сообщении обязателен tool_call_id, совпадающий с id вызова. Сообщение tool без парного вызова нарушает контракт — часть провайдеров отвергает такой запрос.

{
  "model": "<из /api/v1/models>",
  "messages": [
    { "role": "system", "content": "Отвечай по-русски, кратко." },
    { "role": "user", "content": "Столица Франции?" },
    { "role": "assistant", "content": "Париж." },
    { "role": "user", "content": "А население?" }
  ]
}

Блоки контента

content — либо строка, либо массив блоков. Типов ровно четыре:

Тип	Поля	Что принимает
`text`	`text`	Текст
`image_url`	`url`, `detail` (`auto`, `low`, `high`)	Ссылка `https://` или `data:`-URI
`input_audio`	`data` (base64), `format` (`wav`, `mp3`)	Только инлайн, base64
`file`	`filename`, `file_data` (data-URL) или `file_url`	Ссылка или инлайн

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Что на картинке и что в таблице рядом?" },
    { "type": "image_url", "image_url": { "url": "https://cdn.example.com/a.png", "detail": "high" } },
    { "type": "file", "file": { "filename": "price.pdf", "file_url": "https://cdn.example.com/price.pdf" } }
  ]
}

Ссылка должна открываться без авторизации — её скачивает провайдер, а не ваш сервер. Файл из хранилища подходит. Разбор всех способов передачи медиа — на странице Медиаввод.

Вызов функций

Полный материал вынесен в отдельный гайд: Вызов функций. Здесь только форма запроса.

{
  "model": "<из /api/v1/models>",
  "messages": [{ "role": "user", "content": "Погода в Москве?" }],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Текущая погода в городе",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ]
}

Ответ приходит с finish_reason: "tool_calls", вызовы лежат в choices[0].message.tool_calls, аргументы — JSON-строкой. Дальше цикл: выполнить функцию, отправить сообщение с ролью tool и тем же tool_call_id, повторить запрос.

Структурированный вывод

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "invoice",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "number": { "type": "string" },
            "total": { "type": "number" }
          },
          "required": ["number", "total"],
          "additionalProperties": false
        }
      }
    },
    "messages": [{ "role": "user", "content": "Извлеки номер и сумму из счёта." }]
  }' | jq -r '.choices[0].message.content'

Разбор response_format, примеры схем и валидация через pydantic и zod — на странице Структурированный вывод.

Рассуждения

{
  "model": "<из /api/v1/models>",
  "reasoning_effort": "medium",
  "messages": [{ "role": "user", "content": "Найди противоречие в этих двух утверждениях." }]
}

Текст рассуждений приходит в choices[0].message.reasoning (и дублируется в reasoning_content), объём — в usage.completion_tokens_details.reasoning_tokens. За рассуждения платят как за выходные токены, поэтому effort напрямую двигает цену. Подробнее — в гайде по токенам рассуждений.

reasoning_effort и reasoning.effort задавать одновременно нельзя — придёт 400. Выберите что-то одно.

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

`stop`

Массив строк, на которых генерация обрывается. Сама строка в результат не входит, а finish_reason становится stop.

{ "stop": ["\n\n", "КОНЕЦ"] }

Ставьте stop осознанно: модель не сможет произнести строку целиком, и наивный ["\n"] порвёт обычный список. Для структурированного вывода лучше response_format, а не stop.

`temperature`

От 0 до 2. Низкие значения ближе к воспроизводимому результату, высокие — к разнообразию.

Фактический диапазон и поведение задаёт провайдер модели, а не платформа: часть моделей принимает только один или два фиксированных значения. temperature: 0 не гарантирует побайтово одинаковый ответ — при одинаковых аргументах повтор может отличаться.

`max_completion_tokens`

Потолок выходных токенов. Это единственный параметр, участвующий в проверке контекстного окна: вместе со входом он резервирует место в context_length, и при нехватке приходит 422 content_too_large. max_tokens — устаревшее имя. Оно переносится в max_completion_tokens, только если новое имя не задано; если заданы оба, побеждает новое имя.

Python

# держите ответ в бюджете
MAX = 800

`n`, `seed`, `logprobs`

Три параметра, поддержка которых зависит от модели. Ни один из них — не переносимый контракт.

Параметр	Что делает	Поддержка
`n`	Сколько вариантов ответа вернуть	Часть моделей возвращает только один вариант и игнорирует `n`. Большие значения вместе с `max_completion_tokens` увеличивают резерв в контекстном окне
`seed`	Попытка сделать выборку воспроизводимой	Работает не у всех провайдеров; там, где работает, воспроизводимость приблизительная, а не гарантированная
`logprobs`, `top_logprobs`	Вернуть логарифмы вероятностей токенов	Поддерживается меньшинством моделей. Поля `choices[].logprobs` у остальных отсутствуют

Молчаливое игнорирование — норма для этой тройки. Вы не получите ни ошибки, ни предупреждения: параметр примется, эффекта не будет. Не стройте на seed воспроизводимость пайплайна и на logprobs — оценку качества, пока не проверите конкретную модель на своих данных.

n > 1 и logprobs в одном запросе — плохая идея: первый расходует квоту выхода кратно больше, второй возвращает объёмный лог, который дорого разбирать.

Неизвестные поля

Тело запроса разбирается по известной схеме, а лишние поля молча игнорируются: ни ошибки, ни предупреждения.

{
  "model": "<из /api/v1/models>",
  "messages": [{ "role": "user", "content": "Привет" }],
  "max_output_tokens": 500,
  "think": true
}

max_output_tokens и think здесь не существуют — запрос пройдёт как обычный «Привет» без ограничения длины и без рассуждений.

Это удобно при переносе кода с другого провайдера: незнакомые параметры не ломают запрос. Это же опасно: опечатка в имени параметра выглядит как «работает», но ничего не делает. Если поведение не изменилось после правки — проверьте имя поля по справочнику.

Что дальше

Вызов функций

Полный цикл: определение, выполнение, возврат результата

Потоковая передача

Показ ответа по частям

Структурированный вывод

JSON-схема, отказы, валидация

Справочник эндпоинта

Полный список полей запроса и ответа

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Роли и порядок

Блоки контента

Вызов функций

Структурированный вывод

Рассуждения

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

`stop`

`temperature`

`max_completion_tokens`

`n`, `seed`, `logprobs`

Неизвестные поля

Что дальше

Вызов функций

Потоковая передача

Структурированный вывод

Справочник эндпоинта

​Роли и порядок

​Блоки контента

​Вызов функций

​Структурированный вывод

​Рассуждения

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

​stop

​temperature

​max_completion_tokens

​n, seed, logprobs

​Неизвестные поля

​Что дальше

Вызов функций

Потоковая передача

Структурированный вывод

Справочник эндпоинта

Роли и порядок

Блоки контента

Вызов функций

Структурированный вывод

Рассуждения

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

`stop`

`temperature`

`max_completion_tokens`

`n`, `seed`, `logprobs`

Неизвестные поля

Что дальше