Интеграция с pAIpe
Полный контракт API: от первого запроса до бюджетов, файлов, streaming и контроля использования.
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.
Authorization: Bearer pp_live_••••••••••
| 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. Он действует на всю организацию, не может быть
привязан к проекту и всегда имеет срок действия.
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-бюджета и безопасное архивирование.
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, задолженность и проектный месячный бюджет.
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.
/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"
/v1/model?id=<public-model-id>
/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
}
inference:create; доступ к чтению пресета ему не нужен.
04B
Prompt caching и стабильная сессия
Сократите задержку повторных длинных запросов, сохраняя provider-neutral контракт и изоляцию организации.
cache_control
Явный краткоживущий cache для совместимой модели: type: ephemeral, TTL
5m
или 1h.
X-Session-Id
Закрепляет workflow за тем же доступным маршрутом. Можно передать как
session_id
в JSON body.
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"}
}'
cache_control.
05
Chat Completions
Контракт совместим с основными полями OpenAI Chat Completions. Ответ содержит фактический usage, использованный для списания.
/v1/chat/completions
| Поле | Тип | Описание |
|---|---|---|
model | string |
Идентификатор из /v1/models или @preset/<slug>
|
preset | string | Альтернативная явная ссылка на пресет организации |
messages | array | От 1 до 256 сообщений |
user | string |
Непрямой ID конечного пользователя, 1–128 символов. Сервер заменяет его
tenant-bound HMAC и возвращает только paipe.end_user_ref.
|
max_tokens | integer | Максимум токенов ответа |
temperature | number | Параметр генерации модели |
tools | array | Описание вызываемых инструментов |
response_format | object | Формат структурированного ответа |
stream | boolean | Потоковая выдача через Server-Sent Events |
Используйте либо max_tokens, либо max_completion_tokens. Одновременная передача обоих полей отклоняется.
"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, внутренний маршрут или сведения о поставщике. Проектный ключ видит только свой проект.
/v1/generation?id=<request-uuid>
{
"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 символа: латинские буквы, цифры,
_
или -.
{
"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"}
}
}
{
"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
у модели.
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice_result",
"strict": true,
"schema": {
"type": "object",
"properties": {"found": {"type": "boolean"}},
"required": ["found"],
"additionalProperties": false
}
}
}
}
{
"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.
Тарифицируемый веб-поиск
Добавьте provider-neutral инструмент paipe:web_search. Модель должна объявлять
tools
и web_search. Платформа резервирует стоимость max_uses, списывает только фактические
usage.server_tool_use.web_search_requests
и возвращает безопасные URL-цитаты. Перед вызовом проверяйте
capabilities.server_tools.web_search
в каталоге моделей.
{
"tools": [{
"type": "paipe:web_search",
"parameters": {
"max_results": 5,
"max_uses": 2,
"max_total_results": 10,
"allowed_domains": ["example.com"]
}
}]
}
Непубличные server-managed инструменты запрещены
Непубличные типы, плагины и расширения без отдельного RUB-тарифа отклоняются до резервирования и отправки модели с кодом 400 unpriced_provider_extension. Модель без возможностей
tools
и web_search
получает 400 unsupported_model_capability.
Безопасное чтение URL
Инструмент paipe:web_fetch
читает страницу или PDF только с явно разрешённых доменов. Обязательны allowed_domains, разрешено до трёх вызовов и до 16 384 токенов извлечённого текста на вызов. Платформа принудительно выбирает direct-fetch без отдельной платы и заранее резервирует максимальный входной контекст.
Оперативную доступность показывает capabilities.server_tools.web_fetch.
{
"tools": [{
"type": "paipe:web_fetch",
"parameters": {
"max_uses": 2,
"max_content_tokens": 4096,
"allowed_domains": ["docs.example.ru"]
}
}]
}
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.
{
"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
}
Поддерживаются PNG, JPEG, WebP и GIF; до 16 изображений и 1 MiB на весь JSON-запрос. Для изображения резервируется максимальная стоимость доступного входного контекста, затем производится точное списание по фактическому usage и возврат остатка.
05C
Файлы и PDF-документы
Передавайте PDF напрямую или предварительно загрузите его в зашифрованное
tenant-scoped хранилище. Выбирайте модель с file
в input_modalities; платформа разрешает только нативную обработку документа.
{
"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
}
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 и сроком хранения.
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
в рублях за миллион аудиотокенов.
{
"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.
{
"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 в рублях, остаток резерва освобождается.
Найти совместимые модели: GET /v1/models?input_modalities=video.
Для inline-видео весь JSON-запрос по-прежнему ограничен 1 MiB.
05F
Speech-to-Text
Распознавайте речь через отдельный endpoint с проверкой аудиоконтейнера,
консервативным резервом и точным рублёвым списанием. Модель должна объявлять
audio
во входных и transcription
в выходных modality.
/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-символов.
/v1/audio/speech
{
"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-ссылкой.
input_references не поддерживаются. Успешное аудио не
сохраняется для replay: повтор вернёт 409 idempotency_replay_unavailable.
05H
Потоковые аудиоответы
Запросите синтезированную речь через Chat Completions с modalities: ["text", "audio"], конфигурацией
audio
и обязательным stream: true. Модель должна объявлять audio в output_modalities, а каталог — отдельную RUB-ставку pricing.audio_output.
{
"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.
Форматы gateway: WAV, MP3, FLAC, OPUS и PCM16. Найти совместимые модели: GET /v1/models?output_modalities=text,audio.
06
Responses
Современный контракт для текстового ввода, структурированных сообщений и tool calling. Запрос проходит через те же лимиты, резервирование и точное рублёвое списание.
/v1/responses
{
"model": "paipe/advanced-chat",
"input": "Кратко объясни атомарный биллинг",
"max_output_tokens": 256
}
stream: true. Терминальное событие
передаётся только после проверки usage и атомарного списания. Поля store,
background
и previous_response_id
отклоняются до обращения к
модели. Ответы на стороне платформы не сохраняются.
07
Embeddings
Создавайте векторные представления для поиска, RAG и классификации. Модель должна объявлять output modality embeddings.
/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.
/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 с точным резервированием опубликованной цены в рублях. Частичный или повреждённый ответ не списывается.
/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
Асинхронная генерация видео
Отправьте задачу, проверяйте локальный статус и скачивайте результат только после атомарного списания по опубликованной цене за секунду.
/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 дней. Сумма возвращается точной десятичной строкой в рублях.
/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": "…"
}
}
| HTTP | Значение | Действие |
|---|---|---|
| 400 | Некорректный запрос | Исправить параметры, не повторять автоматически |
| 402 | Недостаточно средств или превышен лимит | Пополнить баланс или изменить лимит |
| 409 | Конфликт idempotency | Проверить ключ и исходную операцию |
| 429 | Rate/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 для каждой логической операции. При безопасном повторе передавайте тот же ключ.
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"])
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)
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"]))