Chat Completions

Конечная точка

POST https://api.tokspan.com/v1/chat/completions

Быстрые примеры

Одинаковый API для всех моделей. Выберите язык:

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")
response = client.chat.completions.create(model="gpt-4o", messages=[{"role":"user","content":"Hello"}])
print(response.choices[0].message.content)

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.TOKSPAN_API_KEY, baseURL: 'https://api.tokspan.com/v1' });
const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });
console.log(response.choices[0].message.content);

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Тело запроса

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

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Поля ответа

Как учитываются токены

Объект usage сообщает о токенах, потреблённых для биллинга:

• prompt_tokens — Токены в ваших входных сообщениях (включая системный промпт, историю и любые прикреплённые медиа, преобразованные в токен-эквиваленты)
• completion_tokens — Токены, сгенерированные моделью в ответе
• total_tokens — Сумма токенов промпта и завершения = то, за что выставляется счёт

Для мультимодальных входных данных (изображения, аудио) провайдеры преобразуют медиа в токен-эквиваленты. GPT-4o учитывает около 85 токенов за изображение низкого разрешения и около 170+ за высокое. В вашей панели управления отображается итоговое количество токенов и стоимость каждого запроса.

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

Установите stream: true для получения токенов в реальном времени по мере генерации моделью. TokSpan использует стандартные Server-Sent Events (SSE) — полностью совместимо с форматом потоковой передачи OpenAI.

Пример

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

Формат фрагментов SSE

Каждый фрагмент — это объект JSON с префиксом data:. Поток завершается строкой data: [DONE]:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Каждый фрагмент содержит объект delta (а не message). Поле content может быть пустым или отсутствовать в последнем фрагменте. Последний фрагмент содержит установленный finish_reason и пустой delta.

Потоковая передача с вызовами инструментов

Когда модель вызывает функцию во время потоковой передачи, фрагменты вызова инструмента приходят в delta с полем tool_calls — имя функции и аргументы передаются инкрементально. Соберите все фрагменты для данного tool_call_id, чтобы составить полный вызов функции, затем отправьте ответное сообщение с role: "tool".

Вызов инструментов / Function Calling

TokSpan поддерживает function calling, совместимый с OpenAI, для всех способных к этому моделей. Определите свои инструменты в запросе, и модели ответят структурированными вызовами функций в JSON, которые ваш код выполнит.

Определение инструментов

Передайте массив tools с определениями функций. Каждая функция требует name, description и JSON Schema parameters:

"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}]

Ответ модели с вызовами инструментов

Когда модель решает вызвать функцию, ответ содержит tool_calls вместо текстового содержимого:

{
  "role": "assistant",
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Paris\"}"
    }
  }]
}

Полный цикл вызова инструментов

1. Отправьте запрос с определениями tools
2. Получите tool_calls в ответе — извлеките имя функции и аргументы
3. Выполните функцию в вашем коде (вызовите ваш API погоды, выполните запрос к базе данных и т. д.)
4. Отправьте результаты обратно в виде сообщения с role: "tool", ссылаясь на tool_call_id
5. Модель отвечает текстом на естественном языке, включающим результаты инструментов

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

Вызов инструментов поддерживается моделями: GPT-4o, GPT-4.1, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 2.5 Pro, Gemini 2.5 Flash, DeepSeek V3, Mistral Large 3, Llama 4, Qwen3 и другими. Проверьте страницу Моделей для получения информации о возможностях каждой модели.

Ввод изображений / Vision

Для мультимодальных моделей, таких как GPT-4o и Claude 4 Vision, включайте изображения как URL-адреса или данные в кодировке base64 в массиве content:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }]
}

Поддерживаемые форматы изображений: PNG, JPEG, WebP, GIF (неанимированные). Максимальный размер изображения зависит от модели — обычно 20 МБ на изображение. Для моделей Claude документы PDF также поддерживаются в качестве визуального ввода.

Режим JSON / Структурированный вывод

Принудительно заставьте модель возвращать корректный JSON, установив response_format:

• Режим JSON: {"type": "json_object"} — Модель возвращает корректный JSON. Необходимо включить слово "JSON" в системный промпт.
• Структурированный вывод: {"type": "json_schema", "json_schema": {...}} — Модель возвращает JSON, соответствующий вашей точной схеме. Поддерживается GPT-4o и более новыми моделями.