Chat Completions

Эндпоинт

Принимает историю сообщений, возвращает ответ модели — целиком или потоком. Обязательных полей два: model и messages. Всё остальное имеет значения по умолчанию.

• Заголовок Authorization: Bearer sk-td-… и Content-Type: application/json.
• Модель указывается полным id из каталога, вместе с вендором.
• Ответ в формате OpenAI — SDK и клиенты разбирают его без адаптеров.

curl https://api.tokendock.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENDOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      { "role": "user", "content": "Привет. Ответь одним предложением." }
    ]
  }'

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

Неизвестные поля игнорируются, поэтому код, написанный под другой вендор, не ломается. Параметры, которые модель не поддерживает, тоже игнорируются — сравнить возможности можно по тегам в каталоге.

Примеры запросов

System-сообщение и параметры генерации

Роль system задаёт правила поведения на весь диалог. Низкая temperature нужна там, где ответ должен быть предсказуемым.

{
  "model": "openai/gpt-4.1-mini",
  "messages": [
    {
      "role": "system",
      "content": "Ты технический ассистент. Отвечай коротко, без вступлений и извинений."
    },
    {
      "role": "user",
      "content": "Чем ClickHouse отличается от PostgreSQL для аналитики?"
    }
  ],
  "temperature": 0.3,
  "max_tokens": 500
}

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

Опишите функции в поле tools — модель сама решит, когда их вызвать. Ответ придёт с finish_reason: "tool_calls", а content будет пустым.

{
  "model": "anthropic/claude-4.5-sonnet",
  "messages": [
    { "role": "user", "content": "Какая сейчас погода в Новосибирске?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Текущая погода в городе",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "Название города" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Аргументы приходят строкой с JSON внутри — её нужно распарсить. Выполните функцию у себя и отправьте результат обратно сообщением с ролью tool и тем же tool_call_id.

{
  "id": "chatcmpl-td-2b7e05c9d41f",
  "object": "chat.completion",
  "created": 1787046102,
  "model": "anthropic/claude-4.5-sonnet",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_td_8a1f",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Новосибирск\",\"units\":\"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 96,
    "completion_tokens": 28,
    "total_tokens": 124
  }
}

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

{ "type": "json_object" } обязывает модель вернуть валидный JSON. Формат полей всё равно опишите в system-сообщении: режим гарантирует синтаксис, а не схему.

{
  "model": "openai/gpt-4.1-mini",
  "messages": [
    {
      "role": "system",
      "content": "Верни только JSON с полями items, delivery и total. Без пояснений."
    },
    {
      "role": "user",
      "content": "Заказ: 2 ноутбука по 89 900 ₽, доставка 1 200 ₽."
    }
  ],
  "response_format": { "type": "json_object" },
  "temperature": 0
}

Поля ответа

Структура одинакова для всех моделей. При stream: true те же поля приходят частями внутри чанков — разбор описан в разделе streaming.

Токены и usage

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

• prompt_tokens — все сообщения запроса вместе с system-промптом, историей диалога и описаниями функций из tools. Длинная история — главный источник роста счёта.
• completion_tokens — сгенерированный текст, аргументы вызовов функций и служебные reasoning-токены у моделей с рассуждениями.
• total_tokens — сумма. Стоимость считается отдельно по входу и выходу: цена выхода у большинства моделей в 3–5 раз выше.

При потоковой выдаче usage приходит в последнем чанке, если в запросе передан { "stream_options": { "include_usage": true } }. Списание происходит по факту ответа, история — в разделе «Расходы» в консоли.

Ограничения

Шлюз одинаков для всех моделей, но сами модели разные. Что именно доступно — видно по тегам и колонке контекста в каталоге.

• tools. Вызов функций умеют не все модели. Если модель их не поддерживает, поле игнорируется и ответ придёт обычным текстом.
• vision. Картинки в content принимают только модели с тегом vision — например openai/gpt-4.1 или anthropic/claude-4.5-sonnet.
• Длина контекста. От 8K у эмбеддинговых моделей до 10M у meta/llama-4-scout. Сумма prompt и completion не должна превышать контекст, иначе ответ оборвётся с finish_reason: "length".
• response_format. Режим json_object поддерживают не все модели: часть провайдеров вернёт ошибку 400.