API / v1 OpenAI-compatible

Интеграция с pAIpe

Полный контракт API: от первого запроса до бюджетов, файлов, streaming и контроля использования.

Base URL: https://api.paipe.ru/v1 Формат: application/json OpenAPI 3.1

01

Быстрый старт

Создайте API-ключ в кабинете и выполните первый запрос. Секрет ключа отображается только один раз.

Запрос
curl https://api.paipe.ru/v1/chat/completions \
  -H "Authorization: Bearer $PAIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-00042" \
  -d '{"model":"example/model","messages":[{"role":"user","content":"Привет!"}],"max_tokens":256}'

02

Аутентификация

Передавайте API-ключ в заголовке Authorization. Права ключа ограничиваются выбранными scopes.

HTTP header
Authorization: Bearer pp_live_••••••••••
Не размещайте секрет в браузерном коде, мобильном приложении или публичном репозитории. Храните его в менеджере секретов на сервере и регулярно ротируйте.
Области доступа API-ключей
ScopeРазрешает
models:readПросмотр моделей и рублёвых тарифов
inference:createСоздание запросов к моделям
inference:cancel Отмена активных streaming-запросов организации
usage:readЧтение статистики использования
billing:read Баланс, кредитная ёмкость и бюджет проекта
presets:readЧтение AI-пресетов и истории версий
presets:write Изолированное управление версиями AI-пресетов
files:readСписок и метаданные PDF в области ключа
files:writeЗагрузка и физическое удаление PDF
keys:manageСерверное управление ключами организации

02A

Управление API-ключами

Для CI/CD и серверной автоматизации создайте в кабинете отдельный ключ только со scope keys:manage. Он действует на всю организацию, не может быть привязан к проекту и всегда имеет срок действия.

Management-ключ нельзя создать или ротировать через API. Его создатель должен сохранять активное членство и роль с правом управления ключами. Секреты новых рабочих ключей возвращаются один раз; все ответы имеют Cache-Control: no-store.

GET · POST

/v1/keys

Список метаданных и выпуск рабочего ключа.

POST · DELETE

/v1/keys/:id/rotate · /v1/keys/:id

Zero-downtime rotation и немедленный отзыв.

Создание рабочего ключа
curl https://api.paipe.ru/v1/keys \
  -H "Authorization: Bearer $PAIPE_KEY_MANAGER" \
  -H "Content-Type: application/json" \
  -d '{"name":"production","scopes":["models:read","inference:create"],"expires_at":"2027-01-31T21:00:00Z"}'

02B

Проекты, центры затрат и бюджеты

Management-ключ со scope keys:manage может автоматизировать полный жизненный цикл tenant-scoped проектов. Текущая роль создателя ключа перепроверяется при каждом запросе.

GET · POST

/v1/projects

Bounded-список и создание проекта с уникальным cost-center code.

GET · PATCH · DELETE

/v1/projects/:id · /v1/projects/:id/budget

Чтение, новая версия месячного RUB-бюджета и безопасное архивирование.

Денежные значения передаются точными decimal-строками с точностью до 9 знаков. Бюджет версионируется без перезаписи истории, период считается по Europe/Moscow. Перед архивированием отзовите активные ключи проекта.
Создание проекта и месячного бюджета
curl https://api.paipe.ru/v1/projects \
  -H "Authorization: Bearer $PAIPE_KEY_MANAGER" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production agents","cost_center_code":"AI-PROD"}'

curl -X PATCH https://api.paipe.ru/v1/projects/$PROJECT_ID/budget \
  -H "Authorization: Bearer $PAIPE_KEY_MANAGER" \
  -H "Content-Type: application/json" \
  -d '{"limit_rub":"125000.50","reason":"Утверждён production-бюджет"}'

02C

Текущий ключ и RUB-баланс

Любой действующий ключ может получить собственные безопасные метаданные и live limits через /v1/key. Для финансовой ёмкости используйте отдельный scope billing:read и /v1/credits.

GET

/v1/key

Собственный settled usage в RUB, применимые ceilings, live RPM-окно и сроки ключа.

GET · billing:read

/v1/credits

Prepaid/postpaid capacity, задолженность и проектный месячный бюджет.

Проектный ключ не получает общий cash balance, кредитный лимит или задолженность компании. Он видит только эффективный остаток своего проекта. Все денежные поля — точные строки в RUB, ответы не кэшируются.
Финансовый мониторинг
curl https://api.paipe.ru/v1/credits \
  -H "Authorization: Bearer $PAIPE_BILLING_KEY"

03

Статус сервиса

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

Проверка состояния
curl "https://api.paipe.ru/v1/status"

04

Доступные модели

Эндпоинт возвращает только доступные вашей организации модели и актуальные цены в рублях. Текстовые и аудиотокены публикуются за 1 млн; image-модели дополнительно содержат variant-aware массив pricing.image_generation.

GET /v1/models
Пример ответа
{
  "object": "list",
  "data": [{
    "id": "example/model",
    "name": "Example Model",
    "context_length": 128000,
    "pricing": {
      "currency": "RUB",
      "unit": "per_million_tokens",
      "input": "125.50",
      "output": "480",
      "image_generation": [{
        "dimension": "output_image",
        "unit": "image",
        "billing_scale": "per_unit",
        "selector": "quality=high;resolution=2k",
        "quality": "high",
        "resolution": "2k",
        "reservation_limit_per_item": "1",
        "price": "9.6"
      }]
    }
  }]
}

Для unit: token поле price означает ₽ за 1 млн image-токенов; для image и megapixel — ₽ за одну единицу. Поле reservation_limit_per_item показывает верхний предел резерва на один output в соответствующей единице. Сначала выбирайте наиболее точный selector качества/разрешения, затем default. Исходная USD-ставка и внутренний маршрут никогда не публикуются.

Поиск и фильтры

Используйте q, input_modalities, output_modalities, supported_parameters, минимальный context и максимальные RUB-цены. Доступны стабильная сортировка, limit/offset и заголовок X-Total-Count.

Подбор мультимодальной модели
curl "https://api.paipe.ru/v1/models?input_modalities=image&context=100000&sort=price-low-to-high" \
  -H "Authorization: Bearer $PAIPE_API_KEY"
GET /v1/model?id=<public-model-id>
GET /v1/models/count Те же фильтры, без pagination

04A

AI-пресеты

Именованные конфигурации модели, системной инструкции и параметров генерации с неизменяемой историей версий.

presets:read

Список, активная конфигурация и история версий организации.

presets:write

Изолированный management scope для новых версий, rollback и архива.

Создать версию из рабочего запроса
curl -X POST https://api.paipe.ru/v1/presets/support-agent/chat/completions \
  -H "Authorization: Bearer $PAIPE_PRESET_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Preset-Reason: Approved production configuration" \
  -d '{
    "model": "paipe/text-pro",
    "messages": [
      {"role":"system","content":"Answer briefly and safely"},
      {"role":"user","content":"This message is not persisted"}
    ],
    "temperature": 0.2,
    "max_completion_tokens": 512
  }'

Повторный capture с тем же slug создаёт новую неизменяемую версию. messages, input и stream не сохраняются. Для Responses используйте POST /v1/presets/:slug/responses. Заголовок X-Preset-Reason обязателен.

Использовать активную версию
{
  "model": "@preset/support-agent",
  "messages": [{"role":"user","content":"Подготовь ответ клиенту"}],
  "temperature": 0.1
}
Параметры запроса переопределяют значения пресета. Системная инструкция хранится как конфигурация: не добавляйте в неё секреты или лишние персональные данные. Runtime-ключу достаточно inference:create; доступ к чтению пресета ему не нужен.

04B

Prompt caching и стабильная сессия

Сократите задержку повторных длинных запросов, сохраняя provider-neutral контракт и изоляцию организации.

cache_control

Явный краткоживущий cache для совместимой модели: type: ephemeral, TTL 5m или 1h.

X-Session-Id

Закрепляет workflow за тем же доступным маршрутом. Можно передать как session_id в JSON body.

Повторяемый workflow
curl https://api.paipe.ru/v1/chat/completions \
  -H "Authorization: Bearer $PAIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: workflow-step-00042" \
  -H "X-Session-Id: agent-workflow-2026-00042" \
  -d '{
    "model":"paipe/text-pro",
    "messages":[{"role":"user","content":"Продолжи анализ"}],
    "cache_control":{"type":"ephemeral","ttl":"1h"}
  }'
Не помещайте персональные данные или секреты в session ID. Сервис сразу заменяет его на HMAC-SHA-256 и хранит только хэш, маршрут и срок жизни — без prompt/output content. Организации с обязательным ZDR не могут включить явный cache_control.

05

Chat Completions

Контракт совместим с основными полями OpenAI Chat Completions. Ответ содержит фактический usage, использованный для списания.

POST /v1/chat/completions
Поля запроса Chat Completions
ПолеТипОписание
modelstring Идентификатор из /v1/models или @preset/<slug>
presetstring Альтернативная явная ссылка на пресет организации
messagesarrayОт 1 до 256 сообщений
userstring Непрямой ID конечного пользователя, 1–128 символов. Сервер заменяет его tenant-bound HMAC и возвращает только paipe.end_user_ref.
max_tokensintegerМаксимум токенов ответа
temperaturenumberПараметр генерации модели
toolsarrayОписание вызываемых инструментов
response_formatobject Формат структурированного ответа
streamboolean Потоковая выдача через Server-Sent Events

Используйте либо max_tokens, либо max_completion_tokens. Одновременная передача обоих полей отклоняется.

Для streaming передайте "stream": true и читайте события data: до маркера [DONE]. Финальное JSON-событие содержит usage. При разрыве соединения сервер перестаёт отправлять контент, но безопасно завершает финансовый расчёт.

Явная отмена streaming-запроса

Отправьте POST /v1/requests/:id/cancel ключом со scope inference:cancel. UUID доступен в X-Request-ID и paipe.request_id. Повтор идемпотентен; резерв удерживается до безопасной сверки фактического usage.

Отмена потока
curl -X POST "https://api.paipe.ru/v1/requests/$REQUEST_ID/cancel" \
  -H "Authorization: Bearer $PAIPE_CANCELLATION_KEY"

Сверка отдельной генерации

Передайте UUID из X-Request-ID или paipe.request_id. Ответ не содержит prompt, output, внутренний маршрут или сведения о поставщике. Проектный ключ видит только свой проект.

GET /v1/generation?id=<request-uuid>
Content-free metadata
{
  "data": {
    "id": "018f3a8f-4f67-7b21-a84d-09f18a1b6d90",
    "object": "generation",
    "operation": "chat_completion",
    "model": "paipe/text-pro",
    "preset": null,
    "status": "succeeded",
    "streamed": false,
    "created_at": "2026-08-11T09:30:00Z",
    "started_at": "2026-08-11T09:30:00Z",
    "completed_at": "2026-08-11T09:30:01Z",
    "latency_ms": 1000,
    "scope": {
      "organization_id": "90ae4b2b-17dc-42fd-a66a-15d8c1cacdc7",
      "project_id": null,
      "project_name": null,
      "cost_center_code": null
    },
    "tokens": {
      "input": 120,
      "output": 36,
      "cached_input": 0,
      "cache_write": 0,
      "reasoning": 0,
      "audio_input": 0,
      "total": 156
    },
    "billed": {"currency": "RUB", "amount": "0.1842"},
    "failure": null
  }
}

Журнал генераций

GET /v1/generations возвращает content-free журнал с точными RUB-суммами, API-ключом, проектом, usage и статусом. Фильтруйте по UTC-периоду до 366 дней, модели, операции, статусу, проекту, ключу или end_user_ref. Подписанный курсор действует 24 часа и привязан к исходной области и фильтрам.

Первая страница
curl --get "https://api.paipe.ru/v1/generations" \
  -H "Authorization: Bearer $PAIPE_API_KEY" \
  --data-urlencode "status=succeeded" \
  --data-urlencode "limit=100"

05A

Функции, structured outputs и reasoning

Управляйте вызовами функций, форматом JSON-ответа и reasoning через единый валидируемый контракт. Возможность должна быть объявлена выбранной моделью в supported_parameters.

Client functions

Модель возвращает аргументы, а функцию безопасно исполняет ваше приложение.

Structured outputs

Ответ ограничивается вашей JSON Schema у совместимых моделей.

Reasoning

Reasoning-токены учитываются в лимите вывода и оплачиваются по фактическому usage.

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

В Chat Completions определение находится в function. В Responses поля функции передаются непосредственно внутри элемента tools. Имена должны быть уникальны и содержать 1–64 символа: латинские буквы, цифры, _ или -.

Chat Completions · функция клиента
{
  "model": "paipe/advanced-chat",
  "messages": [{"role": "user", "content": "Найди счёт INV-42"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "lookup_invoice",
      "description": "Найти счёт по номеру",
      "strict": true,
      "parameters": {
        "type": "object",
        "properties": {"number": {"type": "string"}},
        "required": ["number"],
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": {
    "type": "function",
    "function": {"name": "lookup_invoice"}
  }
}
Responses · функция клиента
{
  "model": "paipe/advanced-chat",
  "input": "Найди счёт INV-42",
  "tools": [{
    "type": "function",
    "name": "lookup_invoice",
    "description": "Найти счёт по номеру",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {"number": {"type": "string"}},
      "required": ["number"],
      "additionalProperties": false
    }
  }],
  "tool_choice": {"type": "function", "name": "lookup_invoice"}
}

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

Для Chat Completions используйте response_format. В Responses эквивалентная схема передаётся через text.format. Перед включением проверьте наличие structured_outputs или response_format у модели.

Chat Completions · JSON Schema
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "invoice_result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"found": {"type": "boolean"}},
        "required": ["found"],
        "additionalProperties": false
      }
    }
  }
}
Responses · JSON Schema
{
  "text": {
    "format": {
      "type": "json_schema",
      "name": "invoice_result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"found": {"type": "boolean"}},
        "required": ["found"],
        "additionalProperties": false
      }
    }
  }
}

Reasoning и лимиты

Передайте reasoning.effort со значением от none до max либо reasoning.max_tokens. Эти поля взаимоисключающие; max_tokens должен быть меньше общего лимита вывода. Модель должна объявлять параметр reasoning.

До 128 функций на запрос. Описание — до 4096 байт. Каждая JSON Schema — до 64 КиБ, 16 уровней вложенности и 2048 узлов.

Безопасное чтение URL

Инструмент paipe:web_fetch читает страницу или PDF только с явно разрешённых доменов. Обязательны allowed_domains, разрешено до трёх вызовов и до 16 384 токенов извлечённого текста на вызов. Платформа принудительно выбирает direct-fetch без отдельной платы и заранее резервирует максимальный входной контекст. Оперативную доступность показывает capabilities.server_tools.web_fetch.

Responses · чтение документации
{
  "tools": [{
    "type": "paipe:web_fetch",
    "parameters": {
      "max_uses": 2,
      "max_content_tokens": 4096,
      "allowed_domains": ["docs.example.ru"]
    }
  }]
}
Клиент платит только за фактические токены модели. Выбор движка и платные fetch-режимы не принимаются. Allowlist ограничивает домены, но содержимое страницы остаётся недоверенным и может содержать prompt injection.

05B

Изображения

Передавайте изображения как публичные HTTPS URL или небольшие base64 data URL в Chat Completions и Responses. Модель должна содержать image в input_modalities.

Chat Completions

Массив messages[].content с частями text и image_url.

Responses

Массив input[].content с частями input_text и input_image.

Chat с изображением
{
  "model": "paipe/vision-pro",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Что изображено?"},
      {
        "type": "image_url",
        "image_url": {
          "url": "https://cdn.example.ru/photo.webp",
          "detail": "low"
        }
      }
    ]
  }],
  "max_completion_tokens": 256
}
Gateway не загружает удалённый URL и не сохраняет текст, data URL или адрес изображения. Контент передаётся внешней модели: персональные данные отправляйте только в рамках утверждённого договора и сценария трансграничной обработки.

Поддерживаются PNG, JPEG, WebP и GIF; до 16 изображений и 1 MiB на весь JSON-запрос. Для изображения резервируется максимальная стоимость доступного входного контекста, затем производится точное списание по фактическому usage и возврат остатка.

05C

Файлы и PDF-документы

Передавайте PDF напрямую или предварительно загрузите его в зашифрованное tenant-scoped хранилище. Выбирайте модель с file в input_modalities; платформа разрешает только нативную обработку документа.

Chat с PDF по HTTPS
{
  "model": "paipe/document-pro",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Перечисли обязательства сторон"},
      {
        "type": "file",
        "file": {
          "filename": "agreement.pdf",
          "file_data": "https://cdn.example.ru/agreement.pdf"
        }
      }
    ]
  }],
  "max_completion_tokens": 512
}
Управляемый PDF до 100 MiB
curl -X POST https://api.paipe.ru/v1/files \
  -H "Authorization: Bearer $PAIPE_FILES_KEY" \
  -F "file=@agreement.pdf;type=application/pdf" \
  -F "retention_hours=24"

{
  "model": "paipe/document-pro",
  "messages": [{
    "role": "user",
    "content": [{
      "type": "file",
      "file": {"file_id": "file_REPLACE_WITH_RETURNED_ID"}
    }]
  }]
}

Предсказуемый биллинг

Нативная обработка оплачивается как input tokens. Клиентское поле plugins и неучтённый OCR fallback отклоняются.

Два безопасных режима

Прямой HTTPS/data URL остаётся transient и ограничен 700 000 байт. Управляемый PDF — до 100 MiB, с антивирусом, AES-256-GCM и сроком хранения.

Прямые PDF не сохраняются. Управляемые PDF хранятся зашифрованно до срока expires_at или явного DELETE, но при inference всё равно передаются внешней модели. Используйте персональные данные только в рамках утверждённого договора и сценария трансграничной обработки.

Найти совместимые модели: GET /v1/models?input_modalities=file. Для inline PDF весь JSON-запрос по-прежнему ограничен 1 MiB.

05D

Аудио

Передавайте аудио в Chat Completions как raw base64 в части input_audio. Модель должна содержать audio в input_modalities, а её прайс-лист — отдельную ставку pricing.audio_input в рублях за миллион аудиотокенов.

Chat с аудиозаписью
{
  "model": "paipe/audio-pro",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Сделай краткую расшифровку"},
      {
        "type": "input_audio",
        "input_audio": {
          "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
          "format": "wav"
        }
      }
    ]
  }],
  "max_completion_tokens": 512
}

Bounded input

Только raw base64, до 700 000 декодированных байт на часть и до 8 аудиофрагментов. URL и data URL отклоняются.

Точный биллинг

prompt_tokens_details.audio_tokens списываются по отдельной RUB-ставке. Без опубликованной audio-цены запрос не уйдёт модели.

Аудио не сохраняется платформой, но передаётся внешней модели. Голос и содержание разговора могут быть персональными данными: используйте их только в утверждённом договором и политикой обработки сценарии.

Форматы: WAV, MP3, AIFF, AAC, OGG, FLAC, M4A, PCM16 и PCM24. Найти совместимые модели: GET /v1/models?input_modalities=audio.

05E

Видео

Передавайте видео в Chat Completions как часть video_url. Модель должна содержать video в input_modalities.

Анализ видео по HTTPS URL
{
  "model": "paipe/video-pro",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Кратко опиши ключевые события"},
      {
        "type": "video_url",
        "video_url": {"url": "https://cdn.example.ru/demo.mp4"}
      }
    ]
  }],
  "max_completion_tokens": 512
}

Два безопасных способа

Публичный HTTPS URL без credentials/fragment либо data:video/...;base64 до 700 000 декодированных байт. Форматы: MP4, MPEG, MOV и WebM; до 4 видео.

Консервативный резерв

До отправки резервируется доступный контекст модели. После ответа списываются фактические input/output tokens в рублях, остаток резерва освобождается.

Платформа не сохраняет видео, но передаёт его внешней модели. Поддержка конкретных URL, включая видеоплатформы, зависит от выбранной модели и маршрута. Не передавайте персональные данные без утверждённого правового основания и сценария трансграничной обработки.

Найти совместимые модели: GET /v1/models?input_modalities=video. Для inline-видео весь JSON-запрос по-прежнему ограничен 1 MiB.

05F

Speech-to-Text

Распознавайте речь через отдельный endpoint с проверкой аудиоконтейнера, консервативным резервом и точным рублёвым списанием. Модель должна объявлять audio во входных и transcription в выходных modality.

POST /v1/audio/transcriptions
Распознавание русской речи
{
  "model": "paipe/transcribe-pro",
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
    "format": "wav"
  },
  "language": "ru",
  "temperature": 0
}

Provider-neutral результат

Ответ содержит публичные id/model, транскрипт и проверенный usage. Внутренние provider, cost и metadata удаляются.

Точное списание

Audio input оплачивается по pricing.audio_input, текстовый output — по обычной output-ставке. Остаток предварительного резерва освобождается.

Платформа не сохраняет аудио и транскрипт, но передаёт аудио внешней модели. Зафиксируйте законное основание, уведомление участников, доступ и срок хранения результата в собственной системе.

05G

Text-to-Speech

Синтезируйте речь через отдельный бинарный endpoint. Модель должна объявлять text во входных и audio в выходных modality, а каталог — ставку pricing.input_characters в рублях за 1 млн Unicode-символов.

POST /v1/audio/speech
Синтез речи в MP3
{
  "model": "paipe/speech-pro",
  "input": "Добро пожаловать в сервис",
  "voice": "neutral",
  "response_format": "mp3",
  "speed": 1.0,
  "user": "customer-user-42"
}

Бинарный ответ

mp3 возвращает audio/mpeg, pcm — raw 16-bit little-endian audio/pcm. Ответ ограничен 32 МБ и не кэшируется.

Приватность и расчёты

Текст и аудио не сохраняются. Точная стоимость по числу символов списывается атомарно до выдачи ответа; user заменяется tenant-bound HMAC-ссылкой.

Voice cloning и input_references не поддерживаются. Успешное аудио не сохраняется для replay: повтор вернёт 409 idempotency_replay_unavailable.

05H

Потоковые аудиоответы

Запросите синтезированную речь через Chat Completions с modalities: ["text", "audio"], конфигурацией audio и обязательным stream: true. Модель должна объявлять audio в output_modalities, а каталог — отдельную RUB-ставку pricing.audio_output.

Генерация речи через SSE
{
  "model": "paipe/audio-pro",
  "messages": [{"role": "user", "content": "Дружелюбно поздоровайся"}],
  "modalities": ["text", "audio"],
  "audio": {"voice": "alloy", "format": "wav"},
  "stream": true,
  "max_completion_tokens": 512
}

Безопасный SSE

Склеивайте choices[].delta.audio.data в порядке получения и декодируйте итоговый base64 один раз. Gateway сохраняет backpressure и удаляет provider metadata из каждого чанка.

Точное списание

completion_tokens_details.audio_tokens учитываются как audio_output_tokens. Неиспользованная часть предварительного резерва освобождается после финального usage.

Аудиобайты и transcript передаются транзитом и не сохраняются платформой. Не пишите SSE-body в клиентские логи. Использование синтетического голоса должно соответствовать утверждённому сценарию, согласиям и запрету на подмену личности.

Форматы gateway: WAV, MP3, FLAC, OPUS и PCM16. Найти совместимые модели: GET /v1/models?output_modalities=text,audio.

06

Responses

Современный контракт для текстового ввода, структурированных сообщений и tool calling. Запрос проходит через те же лимиты, резервирование и точное рублёвое списание.

POST /v1/responses
Пример запроса
{
  "model": "paipe/advanced-chat",
  "input": "Кратко объясни атомарный биллинг",
  "max_output_tokens": 256
}
Поддерживаются обычный ответ и SSE с stream: true. Терминальное событие передаётся только после проверки usage и атомарного списания. Поля store, background и previous_response_id отклоняются до обращения к модели. Ответы на стороне платформы не сохраняются.

07

Embeddings

Создавайте векторные представления для поиска, RAG и классификации. Модель должна объявлять output modality embeddings.

POST /v1/embeddings
Пакетный запрос
{
  "model": "paipe/text-embedding",
  "input": ["Первый документ", "Второй документ"],
  "encoding_format": "float"
}

Допускается строка, массив до 256 непустых строк или мультимодальные объекты с текстом и HTTPS/data URL изображениями. До 16 изображений, JSON — до 1 MiB. Модель должна поддерживать image; формат — только encoding_format: float. При изображениях резервируется полный контекст, а списание выполняется по фактическим input tokens.

07A

Rerank

Переранжируйте документы по релевантности запросу. Модель должна объявлять input modality text и output modality rerank.

POST /v1/rerank
Поиск наиболее релевантных документов
{
  "model": "paipe/rerank-pro",
  "query": "Как развернуть отказоустойчивый API?",
  "documents": [
    "Используйте несколько stateless API-нод",
    {"text": "Храните общее состояние в PostgreSQL"},
    {"text": "Схема кластера", "image": "https://cdn.example.ru/cluster.png"}
  ],
  "top_n": 2
}

До 256 документов и 16 изображений, JSON — до 1 MiB. Изображения проходят те же проверки HTTPS/data URL и лимит 700 000 декодированных байт. До вызова резервируется верхняя оценка для каждой пары query/document; после строгой проверки индексов, уникальности и сортировки списывается только подтверждённый usage.total_tokens. Поле document восстанавливается из исходного запроса, поэтому внешний сервис не может подменить возвращаемый текст или добавить свои metadata.

07B

Генерация изображений

Создавайте изображения через отдельный endpoint с точным резервированием опубликованной цены в рублях. Частичный или повреждённый ответ не списывается.

POST /v1/images
Текст в изображение
{
  "model": "paipe/image-pro",
  "prompt": "Фотография товара на нейтральном фоне",
  "n": 1,
  "output_format": "png"
}

Ответ содержит полный массив base64 PNG/JPEG/WebP. До 16 референсов можно передать через input_references. Output-тарифы поддерживают image, megapixel и token: до вызова резервируется опубликованный верхний предел, после проверки списывается точное количество изображений, пикселей или output tokens. Внешние референсы тарифицируются поштучно. При stream: true bounded SSE-превью передаются по мере готовности, а терминальное событие — только после точного списания.

07C

Асинхронная генерация видео

Отправьте задачу, проверяйте локальный статус и скачивайте результат только после атомарного списания по опубликованной цене за секунду.

POST /v1/videos GET /v1/videos/:id /v1/videos/:id/content
Постановка задачи
{
  "model": "paipe/video-pro",
  "prompt": "Медленный пролёт над лесным озером",
  "duration": 5,
  "resolution": "720p",
  "generate_audio": false
}

Доступные модели, capabilities и RUB-тарифы возвращает GET /v1/videos/models. Повтор с тем же Idempotency-Key возвращает тот же job. Статусы pending, in_progress и completed образуют обычный lifecycle; при неоднозначном исходе резерв остаётся в безопасной сверке. Video API запрещён для организаций с обязательным ZDR. Prompt, референсы и сгенерированные bytes не сохраняются pAIpe.

08

Использование и расходы

Получите агрегированную статистику организации или неизменяемо привязанного к ключу проекта за 1–366 дней. Сумма возвращается точной десятичной строкой в рублях.

GET /v1/usage?days=30
Пример ответа
{
  "object": "usage.summary",
  "period": {"days": 30, "timezone": "Europe/Moscow"},
  "scope": {"organization_id": "90ae4b2b-17dc-42fd-a66a-15d8c1cacdc7", "project_id": null},
  "requests": 1842,
  "tokens": {"input": 2700000, "output": 640000, "total": 3340000},
  "images": {"output": 12, "references": 3, "output_pixels": 12582912, "output_megapixels": "12.582912"},
  "video": {"seconds": 35},
  "billed": {"currency": "RUB", "amount": "1725.84"}
}

09

Безопасные повторы

Для каждого логического запроса создавайте стабильный Idempotency-Key длиной 8–128 ASCII-символов.

  • Повтор с тем же ключом и другим телом вернёт 409 idempotency_conflict.
  • Идентификатор операции возвращается в заголовке x-request-id.
  • Не повторяйте запрос с новым ключом после сетевого таймаута, пока не определён результат исходной операции.

10

Ошибки

Ошибки всегда возвращаются в JSON с машинным code и безопасным сообщением без внутренних данных провайдера.

Организационная политика чувствительных данных проверяется до резервирования средств. Блокировка возвращает 403 content_guardrail_blocked, а недоступная безопасная проверка — 503 content_guardrail_unavailable с Retry-After: 60. Эти ответы не создают inference request и не изменяют баланс.
Формат ошибки
{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credit",
    "message": "Insufficient account credit",
    "request_id": "…"
  }
}
Коды ошибок API и рекомендуемые действия
HTTPЗначение Действие
400Некорректный запрос Исправить параметры, не повторять автоматически
402Недостаточно средств или превышен лимит Пополнить баланс или изменить лимит
409Конфликт idempotency Проверить ключ и исходную операцию
429Rate/concurrency limit Дождаться Retry-After, затем повторить с backoff и jitter
502–504Временная ошибка модели Повторить с тем же Idempotency-Key

11

Текущие ограничения

Эти ограничения являются частью публичного контракта текущей версии API.

Размер JSON

до 1 MiB

Сообщений

до 256

Streaming

SSE с финальным usage

Валюта расчётов

RUB

Inference-ответы возвращают RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. При временной ошибке соблюдайте Retry-After и сохраняйте исходный Idempotency-Key.

12

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

Используйте серверное окружение, явный timeout и новый Idempotency-Key для каждой логической операции. При безопасном повторе передавайте тот же ключ.

Python 3 · стандартная библиотека
import json, os, uuid, urllib.request

payload = {
    "model": "paipe/advanced-chat",
    "messages": [{"role": "user", "content": "Привет!"}],
    "max_completion_tokens": 256,
}

request = urllib.request.Request(
    "https://api.paipe.ru/v1/chat/completions",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['PAIPE_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=120) as response:
    completion = json.load(response)
    print(completion["choices"][0]["message"]["content"])
Node.js 20+ · built-in fetch
import { randomUUID } from "node:crypto"

const response = await fetch("https://api.paipe.ru/v1/chat/completions", {
  method: "POST",
  signal: AbortSignal.timeout(120_000),
  headers: {
    Authorization: `Bearer ${process.env.PAIPE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "paipe/advanced-chat",
    messages: [{ role: "user", content: "Привет!" }],
    max_completion_tokens: 256,
  }),
})

const body = await response.json()
if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
console.log(body.choices[0].message.content)
Elixir · Req
idempotency_key =
  "req_" <> Base.url_encode64(:crypto.strong_rand_bytes(18), padding: false)

response =
  Req.post!("https://api.paipe.ru/v1/chat/completions",
    auth: {:bearer, System.fetch_env!("PAIPE_API_KEY")},
    headers: [{"idempotency-key", idempotency_key}],
    receive_timeout: 120_000,
    retry: false,
    json: %{
      "model" => "paipe/advanced-chat",
      "messages" => [%{"role" => "user", "content" => "Привет!"}],
      "max_completion_tokens" => 256
    }
  )

if response.status != 200, do: raise(inspect(response.body["error"]))
IO.puts(get_in(response.body, ["choices", Access.at(0), "message", "content"]))
Полный машиночитаемый контракт доступен в OpenAPI 3.1 . Генерируйте типизированные клиенты только из зафиксированной версии спецификации и проверяйте изменения контракта перед обновлением.