API, совместимый с OpenAI

Что это такое

API, совместимый с OpenAI, позволяет инструменту, работающему с форматом chat completions от OpenAI, использовать чат-модели ToRun с оплатой из вашего аккаунта ToRun. Агент для программирования, такой как opencode, может использовать ToRun как поставщика моделей наряду с MCP-инструментами ToRun.

Адрес и вход

Используйте тот же ключ разработчика, что и для MCP-сервера: см. Ключи разработчика. Ключ, созданный до появления API, совместимого с OpenAI, получает ответ 403 insufficient_scope. Права ключа никогда не меняются, поэтому создайте новый ключ.

У API две конечные точки: GET /v1/models и POST /v1/chat/completions. Любой другой путь в /v1 отвечает 404 not_found.

Модели

GET /v1/models сначала выдаёт torun/auto, а затем все текстовые модели, доступные вашему тарифу, по их id. Для каждой модели указано:

• сколько текста она может прочитать (context_length) и насколько длинный ответ может написать (max_completion_tokens),
• умеет ли она вызывать инструменты (supports_tools) и читать изображения (supports_vision),
• её цена в Runs за миллион токенов (pricing: input и output).

torun/auto позволяет ToRun выбирать модель для каждого запроса: ту, что читает изображения, если в запросе есть изображение, и ту, что вызывает инструменты, если он отправляет tools.

Chat completions

POST /v1/chat/completions принимает:

• messages с ролями system, developer (обрабатывается как system), user, assistant и tool,
• tools и tool_choice (auto, none, required или одна названная функция): собственные инструменты вашего инструмента возвращаются к нему как вызовы инструментов, и ToRun никогда их не выполняет,
• response_format с json_object. json_schema принимается, и ответ приходит в JSON, но сама схема не применяется принудительно,
• temperature (от 0 до 2), top_p (от 0 до 1), max_completion_tokens или max_tokens, stop (до 4 последовательностей), seed и reasoning_effort,
• stream и stream_options.include_usage.

n больше 1, logprobs, top_logprobs, аудио и любой вывод, кроме текста, отклоняются с 400 unsupported_parameter, а не игнорируются.

Изображения

Отправляйте изображение встроенным, в виде data:image/...;base64,... в части image_url, до 20 МБ на запрос. Изображение, отправленное ссылкой, отклоняется с 400 image_url_not_supported: ToRun его не загружает. Изображения проходят проверку безопасности, как и в приложении.

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

При "stream": true ответ приходит в виде server-sent events в формате chat.completion.chunk:

• Первый фрагмент содержит роль assistant, а вызовы инструментов передаются потоком со своим index.
• Пока отправлять нечего, каждые 15 секунд приходит строка комментария : keepalive; парсеры SSE её пропускают.
• data: [DONE] завершает успешный поток.
• С stream_options.include_usage последний фрагмент имеет пустой choices и содержит usage.
• Сбой после начала потока приходит одним событием data: {"error": ...}, без [DONE].

Вызов без потоковой передачи прерывается через 110 секунд с 504 timeout. Отправляйте длинные запросы с "stream": true.

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

usage содержит prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens и completion_tokens_details.reasoning_tokens, а также torun_credits — сколько стоил вызов в Runs.

Использование в opencode

Конфигурация opencode на странице «Разработчикам» добавляет ToRun как поставщика моделей рядом с MCP-сервером:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "torun": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ToRun",
      "options": { "baseURL": "https://mcp.torun.ai/v1", "apiKey": "{env:TORUN_API_KEY}" },
      "models": { "torun/auto": { "name": "ToRun Auto" } }
    }
  }
}

Любой другой инструмент, работающий с чат-API OpenAI, работает так же. На вкладке «OpenAI API» этой страницы показан такой вызов:

curl https://mcp.torun.ai/v1/chat/completions \
  -H "Authorization: Bearer $TORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "torun/auto", "messages": [{"role": "user", "content": "Hello"}]}'

Как оплачиваются вызовы

Вызовы API стоят столько же Runs, сколько такое же использование в приложении. Их оплачивают только платные средства: сначала лимит вашего платного тарифа, затем кошелёк, если вы разрешили это для ключа. Бесплатный лимит никогда не оплачивает вызовы API. Действуют месячный и дневной лимиты ключа, а ответы проходят проверку безопасности так же, как ответы в чате.

Ограничения

Каждый ключ может отправлять этому API 60 запросов в минуту и выполнять 4 completions одновременно. При превышении API отвечает 429 rate_limit_exceeded с заголовком Retry-After.

Ошибки

Каждая ошибка имеет вид {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message приходит на языке, который запрашивает заголовок Accept-Language запроса.

Запрос, который нельзя оплатить, получает ответ 402, а не 429, чтобы клиент не повторял его снова и снова.