Документация API RUFP — подключение и справочник

RUFP API · v1

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

Выберите метод, чтобы увидеть его назначение, запрос, ответ и возможные ошибки.

OpenAI-совместимый формат

Подключение

Базовый URL: https://app.rufp.ru/api/v1/llm
Модель: rufp/default

Создайте ключ в разделе API личного кабинета и передавайте его в каждом запросе. В примерах замените YOUR_API_KEY на свой ключ.

Заголовок авторизации

Authorization: Bearer YOUR_API_KEY

GET/modelsСписок моделей и ограничения

Возвращает доступную модель и ограничения её профиля. Используйте при настройке клиента, чтобы получить идентификатор модели и допустимый размер контекста и ответа.

Сейчас публичный идентификатор — rufp/default. При смене внутренней модели этот идентификатор менять в клиенте не требуется. Ограничения можно обновлять через этот метод.

Запрос

Заголовок Authorization обязателен. Тела запроса и query-параметров нет.

Запрос · cURL

curl "https://app.rufp.ru/api/v1/llm/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ · 200 OK

Content-Type: application/json. Числа и ревизия в примере условные: используйте значения из своего ответа.

Ответ · JSON

{
  "object": "list",
  "data": [
    {
      "id": "rufp/default",
      "object": "model",
      "created": 0,
      "owned_by": "rufp",
      "profile_revision": "example-profile-revision",
      "limits": {
        "context": 128000,
        "output": 8192,
        "preserve_recent_tokens": 16000
      }
    }
  ]
}

Поле	Тип / обязательность	Описание
`object`	string	Тип ответа: list.
`data`	array	Список доступных моделей.
`data[].id`	string	Передавайте в поле model при запросе ответа.
`data[].object / owned_by`	string	Тип записи model и владелец rufp.
`data[].created`	integer	Служебное поле совместимости; сейчас возвращается 0.
`data[].profile_revision`	string	Ревизия настроек. Можно передавать в x-rufp-model-profile-revision для проверки актуальности.
`data[].limits.context`	integer · токены	Размер контекстного окна модели.
`data[].limits.output`	integer · токены	Максимальный размер ответа модели.
`data[].limits.preserve_recent_tokens`	integer · токены	Размер недавней истории, сохраняемой при сокращении контекста.

Ошибки и действия клиента

При ошибке HTTP проверьте статус и объект error. Поле requestId помогает поддержке найти запрос. Ниже перечислены основные ошибки.

Пример ошибки · HTTP 401

{
  "error": {
    "code": "auth_required",
    "message": "Invalid rufp API key",
    "requestId": "example-request-id"
  }
}

HTTP	error.code	Что делать
401	`auth_required`	Ключ не передан, неверен или отозван. Проверьте Authorization и действующий ключ в кабинете.
403	`billing_blocked`	Доступ к аккаунту ограничен. Обратитесь в поддержку.

POST/chat/completionsПолучить ответ модели

Передайте историю разговора и получите следующий ответ модели. Метод используется в чатах, ботах, скриптах и приложениях; один и тот же адрес принимает текст, изображения, PDF и описания инструментов.

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

Тело — JSON. Обязательные заголовки: Authorization и Content-Type: application/json.

Поле	Тип / обязательность	Описание
`model`	string · необязательно	Рекомендуем явно передавать rufp/default. Если поле отсутствует, используется модель по умолчанию.
`messages`	array · обязательно	Хотя бы одно сообщение. Передавайте историю, нужную для следующего ответа.
`messages[].role`	string · обязательно	system — инструкции; user — вопрос; assistant — предыдущий ответ; tool — результат вызова инструмента.
`messages[].content`	string / array / null	Текст либо массив текстовых частей и вложений. В сообщении assistant с tool_calls может быть null.
`stream`	boolean · необязательно	false — готовый JSON; true — поток SSE. По умолчанию true.
`tools`	array · необязательно	Описания функций: type: function, имя, описание и JSON Schema параметров. См. пример «Инструменты».
`messages[].tool_calls`	array · для assistant	Вызовы функций из предыдущего ответа модели. Верните их в истории следующего запроса.
`messages[].tool_call_id`	string · для tool	Идентификатор вызова, которому соответствует результат инструмента.

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

Текст · JSON

Отправьте вопрос и получите готовый ответ одним JSON-объектом. Подходит для скриптов и обработки результата после завершения запроса.

Запрос · cURL

curl "https://app.rufp.ru/api/v1/llm/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "rufp/default",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "Сколько будет 2 × 2?"
    }
  ]
}'

Ответ · 200 OK · application/json

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1790179200,
  "model": "rufp/default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "2 × 2 = 4."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 5,
    "total_tokens": 25
  },
  "billing": {
    "type": "subscription",
    "currency": "RUB",
    "pricing_version": "rufp-public-api-v1",
    "subscription": {
      "monthly_limit_percent_used": "0.010000",
      "equivalent_rub": "0.25"
    },
    "balance_charged_rub": "0.00"
  }
}

Текст, токены и расход в примерах иллюстративные. Фактические значения вернёт сервер.

Поток · SSE

При stream: true и при отсутствии поля stream ответ приходит событиями data:. Последнее JSON-событие содержит billing, после него приходит data: [DONE]. Проверяйте события с error внутри потока.

Потоковый запрос · cURL

curl --no-buffer --request POST 'https://app.rufp.ru/api/v1/llm/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "rufp/default",
    "stream": true,
    "messages": [{"role": "user", "content": "Напиши короткое приветствие."}]
  }'

Инструменты

Передайте описания функций в tools. Если модель вернула tool_calls, выполните вызов в своём приложении. В следующем запросе передайте сообщение assistant с вызовом и сообщение role: "tool" с результатом и тем же tool_call_id. В SSE аргументы инструмента могут приходить частями.

Запрос с инструментом · JSON

{
  "model": "rufp/default",
  "stream": false,
  "messages": [{"role": "user", "content": "Какая сейчас погода в Москве?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить текущую погоду в городе",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

Изображение

Передавайте изображение частью image_url в messages[].content. Замените многоточие реальным содержимым файла в Base64; локальный путь к файлу не передаёт его содержимое.

Содержимое сообщения · JSON

[
  {"type": "text", "text": "Что изображено на картинке?"},
  {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]

PDF

Передавайте PDF частью file в messages[].content. Доступ зависит от тарифа и ограничений. При pdf_fallback_required преобразуйте файл в текст или изображения и повторите запрос. Обычный текстовый файл прочитайте на стороне клиента и передайте его содержимое как текст сообщения.

Содержимое сообщения · JSON

[
  {"type": "text", "text": "Кратко перескажи документ."},
  {"type": "file", "file": {
    "filename": "document.pdf",
    "file_data": "data:application/pdf;base64,..."
  }}
]

Поля успешного ответа

Поле	Тип / обязательность	Описание
`id / created`	string / integer	Идентификатор ответа и время создания в Unix-секундах.
`object`	string	chat.completion для JSON; chat.completion.chunk для SSE.
`model`	string	Публичный идентификатор rufp/default.
`choices[].message.content`	string / null	Текст готового ответа в JSON.
`choices[].delta`	object · SSE	Очередная часть ответа или вызова инструмента.
`choices[].message.tool_calls`	array · при вызове функции	id, type и function с полями name и arguments. arguments — строка с JSON-параметрами.
`choices[].finish_reason`	string / null	Причина завершения: например, stop, length или tool_calls. В промежуточных SSE-событиях — null.
`usage`	object · если присутствует	Статистика токенов: prompt_tokens, completion_tokens, total_tokens. В SSE не обязана присутствовать в каждом событии.
`billing`	object	Итоговый расход запроса. В JSON — в ответе; в SSE — в последнем JSON-событии перед [DONE].

Расход запроса · billing

Поле	Тип / обязательность	Описание
`type`	string	subscription — лимиты подписки; balance — деньги с баланса API. Источник выбирается перед началом запроса.
`currency / pricing_version`	string	RUB и версия расчёта rufp-public-api-v1.
`subscription.monthly_limit_percent_used`	string	Доля месячного лимита, потраченная этим запросом, в процентах; это не общий расход за месяц.
`subscription.equivalent_rub`	string	Оценка использованной части подписки в рублях. Это не отдельное списание денег.
`balance_charged_rub`	string	Сколько списано с баланса API. При оплате лимитами подписки — 0.00.

Рубли и проценты передаются строками. При оплате с баланса поле subscription равно null.

billing · оплата с баланса API

{
  "billing": {
    "type": "balance",
    "currency": "RUB",
    "pricing_version": "rufp-public-api-v1",
    "subscription": null,
    "balance_charged_rub": "0.50"
  }
}

Ошибки и действия клиента

Пример ошибки · HTTP 401

{
  "error": {
    "code": "auth_required",
    "message": "Invalid rufp API key",
    "requestId": "example-request-id"
  }
}

HTTP	error.code	Что делать
401	`auth_required`	Ключ не передан, неверен или отозван. Проверьте Authorization и действующий ключ в кабинете.
403	`billing_blocked`	Доступ к аккаунту ограничен. Обратитесь в поддержку.
400	`bad_request`	Проверьте JSON, сообщения, название модели и последовательность вызовов инструментов.
402	`subscription_required`	Нет действующей платной подписки. Оформите или продлите её.
402	`quota_exceeded`	Лимиты исчерпаны, оплата с баланса выключена. Дождитесь сброса лимитов или включите оплату с баланса API.
402	`insufficient_balance`	Для запроса нужен баланс API, но он равен нулю или отрицательный. Пополните его до положительного значения.
409	`model_profile_revision_mismatch`	Профиль изменился. Снова вызовите GET /models и обновите x-rufp-model-profile-revision.
413	`body_too_large / media_request_too_large`	Запрос или вложения слишком большие. Уменьшите их объём.
422	`pdf_fallback_required`	PDF не удалось обработать напрямую. Преобразуйте его в текст или изображения и отправьте новый запрос.
429	`rate_limited`	Достигнут лимит одновременных запросов или сервис занят. Повторите запрос позже.
503	`upstream_busy / upstream_unavailable / media_upstream_unavailable / api_pricing_unavailable`	Сервис временно недоступен. Повторите запрос позже; при длительной ошибке передайте requestId в поддержку.

В уже начавшемся SSE-потоке ошибка может прийти событием с полем error: проверяйте его отдельно от HTTP-статуса. Обрыв соединения не отменяет уже учтённый расход.

Дополнительные заголовки запроса к модели

Поле	Тип / обязательность	Описание
`x-rufp-session-id`	string · необязательно	Стабильный идентификатор разговора для media-контекста. Используйте отдельное значение для каждого разговора. Не заменяет историю messages.
`x-rufp-model-profile-revision`	string · необязательно	profile_revision из GET /models. При несовпадении сервер вернёт 409: обновите профиль и повторите запрос.

Условия доступа, лимиты и баланс

Для запросов нужна действующая платная подписка. Подписка, выданная командой, тоже подходит.
Лимиты общие с приложением RUFP. Сначала расходуются они.
После исчерпания лимитов запрос возможен, если включена оплата с баланса API и баланс положительный. При выключенном тумблере запрос отклоняется, даже если деньги есть.
Один запрос целиком учитывается по источнику, выбранному перед его началом. Итоговое списание может увести баланс в минус.
Следующий запрос с баланса доступен после пополнения до положительного значения. Доступные лимиты подписки работают и при отрицательном балансе.
Пополнение в кабинете доступно только при действующей платной подписке: от 100 ₽ целыми рублями. Пополнение само не включает оплату с баланса.

API-ключ разрешает только два метода из этого справочника. Создание и удаление ключей, настройка оплаты и пополнение выполняются в личном кабинете.