Документация API

Полное руководство по интеграции с API zapros.ai

Base URL

https://zapros.ai/api/v1

API совместим с OpenAI — подставьте этот base_url в любой OpenAI-совместимый SDK, и всё заработает.

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

Начните использовать API zapros.ai за 3 простых шага:

1

Зарегистрируйтесь

Создайте аккаунт на zapros.ai/register. Понадобится только email и пароль.

2

Получите API-ключ

В личном кабинете перейдите в раздел API-ключи и создайте новый ключ. Он будет иметь вид zpr_xxx...

3

Сделайте первый запрос

Пополните баланс и вызовите API. Пример ниже:

curl
curl -X POST https://zapros.ai/api/v1/chat/completions \
  -H "Authorization: Bearer zpr_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      {"role": "user", "content": "Привет!"}
    ]
  }'

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

Inference-запросы должны содержать заголовок Authorization с ключом zpr_:

Authorization: Bearer zpr_ваш_ключ

Важно: Никогда не передавайте ваш API-ключ в клиентском коде. Management REST и MCP принимают отдельный ручной токен zpm_ или короткоживущий OAuth zpo_, выпущенный строго для соответствующего resource. OAuth-подключения MCP и Management используют разные grants и tokens; их нельзя взаимозаменять.

Chat Completions

Основной эндпоинт для генерации текста. Полностью совместим с форматом OpenAI.

Запрос

POST /api/v1/chat/completions
{
  "model": "openai/gpt-5-nano",    // Обязательно. Идентификатор модели
  "messages": [                    // Обязательно. Массив сообщений
    {
      "role": "system",            // system | user | assistant
      "content": "Ты полезный ассистент"
    },
    {
      "role": "user",
      "content": "Привет!"
    }
  ],
  "stream": false,                 // Потоковый вывод (SSE)
  "temperature": 0.7,              // Креативность (0.0 - 2.0)
  "max_tokens": 1024               // Макс. кол-во токенов в ответе
}
Поддерживаются стандартные параметры OpenAI: top_p, stop, tools (function calling), tool_choice, response_format и другие. Поддержка конкретного параметра зависит от модели.

Ответ

200 OK
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1719000000,
  "model": "openai/gpt-5-nano",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Responses API

Современный OpenAI-совместимый интерфейс для reasoning, structured outputs и function calling. Поддерживает обычные и потоковые ответы.

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "zpr_ваш_ключ",
  baseURL: "https://zapros.ai/api/v1",
});

const response = await client.responses.create({
  model: "openai/gpt-5-nano",
  input: "Кратко объясни квантовую запутанность",
  max_output_tokens: 1024,
  reasoning: { effort: "medium" },
  store: false,
});

console.log(response.output_text);

OpenRouter Responses работает без серверного хранения истории: используйте store: false и передавайте всю историю в input. Параметр previous_response_idне поддерживается. Доступны image understanding, PDF по URL или data URI (с бесплатным Cloudflare parser) и ограниченный server tool openrouter:web_search с engine exa, parallel или perplexity. Legacy web plugin, X search, shared file_id, audio, video и output image отключены; клиентские function tools работают.

Ограниченный web search

Укажите жёсткие лимиты использования и результатов. Оплачиваются inference-проходы, возможная доплата модели и выбранный поисковый движок.

POST /api/v1/responses
{
  "model": "openai/gpt-5-nano",
  "input": "Что важного произошло сегодня?",
  "tools": [{
    "type": "openrouter:web_search",
    "parameters": {
      "engine": "exa",
      "max_uses": 2,
      "max_results": 5,
      "max_total_results": 10
    }
  }],
  "max_tool_calls": 2
}

Streaming Responses

javascript
const stream = await client.responses.create({
  model: "openai/gpt-5-nano",
  input: "Напиши короткое приветствие",
  stream: true,
  store: false,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Responses использует события вида response.output_text.delta, а не choices[].delta из Chat Completions.

Embeddings

Создавайте векторы для поиска, RAG и кластеризации через OpenAI-совместимый endpoint. Можно передать одну строку или пакет строк; тарифицируются входные токены.

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "zpr_ваш_ключ",
  baseURL: "https://zapros.ai/api/v1",
});

const result = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: ["Первый документ", "Второй документ"],
});

console.log(result.data[0].embedding);

Сейчас включены безопасно тарифицируемые text-only запросы без streaming. Media-входы и готовые массивы token ID отклоняются; параметры dimensions и input_type пока отключены, потому что OpenRouter не публикует их поддержку для каждой модели. Разбивайте большие документы на текстовые фрагменты.

Видео

Запустите асинхронную генерацию через POST /api/v1/videos, затем проверяйте состояние через GET /api/v1/videos/{id} ключом того же аккаунта. Видео тарифицируется посекундно; стоимость зависит от модели, длительности и поддержки аудио.

POST /api/v1/videos
curl https://zapros.ai/api/v1/videos   -H "Authorization: Bearer zpr_ваш_ключ"   -H "Content-Type: application/json"   -d '{
    "model": "google/veo-3.1-fast",
    "prompt": "Спокойный пролёт над лесом",
    "duration": 8
  }'

duration принимает только поддерживаемые моделью значения, audio — строго boolean. Для image-to-video моделей передайте HTTP(S)-ссылку в image_url. Неуспешные задачи автоматически возвращают зарезервированные средства.

Стриминг Chat Completions

Для POST /chat/completions при "stream": true ответ приходит по частям в формате Server-Sent Events:

SSE stream
data: {"choices":[{"delta":{"content":"Привет"},"finish_reason":null}]}

data: {"choices":[{"delta":{"content":"!"},"finish_reason":null}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Python

python
from openai import OpenAI

client = OpenAI(api_key="zpr_ваш_ключ", base_url="https://zapros.ai/api/v1")

stream = client.chat.completions.create(
    model="openai/gpt-5-nano",
    messages=[{"role": "user", "content": "Привет!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

JavaScript

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "zpr_ваш_ключ",
  baseURL: "https://zapros.ai/api/v1",
});

const stream = await client.chat.completions.create({
  model: "openai/gpt-5-nano",
  messages: [{ role: "user", content: "Привет!" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Модели и цены

Список всех доступных моделей и цен — на странице Модели и цены. Идентификатор модели указывается в поле model целиком, вместе с провайдером (например anthropic/claude-sonnet-5).

Получить список моделей программно:

GET /api/v1/models
curl https://zapros.ai/api/v1/models \
  -H "Authorization: Bearer zpr_ваш_ключ"

Этот endpoint возвращает модели для Chat Completions и Responses. Каталог эмбеддингов доступен отдельно:

GET /api/v1/embeddings/models
curl https://zapros.ai/api/v1/embeddings/models \
  -H "Authorization: Bearer zpr_ваш_ключ"

В pricing указаны рублёвые ставки с единицами: input_per_m, output_per_m, request_rub_per_inference, image_rub_per_image_per_inference и web_search_rub_per_use. Поля input_modalities и supported_endpoints помогают выбрать совместимую модель.

Лимиты и оплата

Оплата — по факту использования: с баланса списывается стоимость каждого запроса по опубликованным единицам тарификации: входные и выходные токены, фиксированные inference/image/web-search доплаты, тариф поискового движка или секунды видео. Все ставки указаны на странице Модели и цены.

  • • Лимит запросов: 200 запросов в минуту на API-ключ. При превышении — код 429.
  • • Баланс: если средств недостаточно, запрос вернёт код 402. Пополнить можно в личном кабинете.
  • • Учёт: фактический расход по токенам и стоимость доступны в разделе «Статистика».
  • • Лимиты ключа: в разделе «API-ключи» можно задать месячный бюджет, максимум на один запрос и список разрешённых моделей. В лимит входят выполняющиеся резервы, поэтому параллельные запросы не обходят бюджет.
  • • Переход старых видео: видео-задачи, созданные до запуска лимитов, исторически не хранили ID ключа и не входят в его месячный расход. Все новые video-запросы учитываются атомарно.

Management API

Для автоматизации аккаунта можно использовать отдельные scoped-токены zpm_.... Создавайте и отзывайте их в разделе Агенты и MCP. Публичный OAuth-клиент должен запросить отдельный resource https://zapros.ai/api/v1/management. Management OAuth использует отдельный grant от MCP; токен одного resource не работает на другом. Ни zpm_, ни zpo_ не позволяют создавать management-токены, пополнять баланс или управлять платежами.

Management OAuth discovery
GET https://zapros.ai/.well-known/oauth-protected-resource/api/v1/management
GET https://zapros.ai/.well-known/oauth-authorization-server
POST https://zapros.ai/oauth/register
GET https://zapros.ai/oauth/authorize?resource=https%3A%2F%2Fzapros.ai%2Fapi%2Fv1%2Fmanagement
POST https://zapros.ai/oauth/token

account:read

Профиль аккаунта и баланс в RUB

models:read

Каталог моделей и расчёт стоимости

keys:read

Метаданные и лимиты inference-ключей

keys:create

Создание ограниченных inference-ключей

keys:update

Изменение inference-ключей

keys:revoke

Безвозвратный отзыв inference-ключей

usage:read

Агрегаты расхода и последние запросы

compute:read

Текущие и будущие CPU/GPU ресурсы

Каталог и оценка стоимости
curl "https://zapros.ai/api/v1/management/models?kind=video&limit=20" \
  -H "Authorization: Bearer zpm_ваш_management_токен"

curl -X POST https://zapros.ai/api/v1/management/cost-estimates \
  -H "Authorization: Bearer zpm_ваш_management_токен" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"chat","model":"openai/gpt-5-nano","input_tokens":2000,"output_tokens":500}'

Оба эндпоинта требуют models:read. Оценка использует текущие цены каталога, не вызывает провайдера, не резервирует баланс и ничего не списывает; фактическая стоимость принятого запроса может отличаться.

Создание ограниченного inference-ключа
curl -X POST https://zapros.ai/api/v1/management/keys -H "Authorization: Bearer zpm_ваш_management_токен" -H "Idempotency-Key: agent-key-2026-10-04" -H "Content-Type: application/json" -d '{
  "name": "Research agent",
  "monthlyBudgetRub": 500,
  "maxRequestRub": 10,
  "allowedModels": ["openai/gpt-5-nano"]
}'

При прямом вызове через доверенный zpm_ новый секрет zpr_ возвращается один раз. OAuth-клиент Management никогда не получает исходный zpr_: ответ содержит только 15-минутный dashboard claim для владельца аккаунта. Месячный бюджет, максимум на запрос и непустой список моделей обязательны. Стабильный Idempotency-Key длиной 8–128 символов делает повтор безопасным и не создаёт дубликат в течение 24 часов, но не восстанавливает секрет после подтверждения или истечения dashboard claim. Такой terminal replay вернёт метаданные claim без секрета; мутации записываются в аудит.

Management endpoints
GET    /api/v1/management/account
GET    /api/v1/management/models?kind=all&limit=50
POST   /api/v1/management/cost-estimates
GET    /api/v1/management/keys
POST   /api/v1/management/keys
PATCH  /api/v1/management/keys/{id}
DELETE /api/v1/management/keys/{id}
GET    /api/v1/management/usage?days=30&limit=50
GET    /api/v1/management/compute/offers
GET    /api/v1/management/compute/instances

MCP для агентов

Stateless JSON-RPC сервер доступен только через POST https://zapros.ai/mcp. Поддерживаются MCP 2026-07-28 и совместимые версии 2025-11-25/2025-06-18; отдельной GET/SSE-сессии нет. Рекомендуемый способ подключения — указать в совместимом клиенте только https://zapros.ai/mcp и пройти Agent Connect OAuth. Готовые инструкции для Claude, Cursor и Codex находятся на странице «Подключить агента». Ручной zpm_ bearer тоже поддерживается и настраивается явно.

Agent Connect OAuth

MCP challenge ведёт к protected-resource metadata по RFC 9728, а она — к authorization-server metadata по RFC 8414. Публичный клиент использует authorization code + S256 PKCE, точный зарегистрированный redirect URI и resource=https://zapros.ai/mcp; client secret не нужен и не принимается. Claude и Codex могут использовать Client ID Metadata Document, а Cursor — ограниченную динамическую регистрацию публичного клиента.

OAuth discovery
GET https://zapros.ai/.well-known/oauth-protected-resource/mcp
GET https://zapros.ai/.well-known/oauth-authorization-server
POST https://zapros.ai/oauth/register
GET https://zapros.ai/oauth/authorize
POST https://zapros.ai/oauth/token

Access token zpo_ обычно живёт 15 минут. Refresh token ротируется при каждом обмене; повторное использование старого refresh token отзывает весь MCP grant. Этот токен предназначен только для MCP. Для Management REST нужен отдельный OAuth grant с resource=https://zapros.ai/api/v1/management; audiences не взаимозаменяются.

На экране согласия пользователь ограничивает общий месячный бюджет всех ключей подключения, максимум на запрос, разрешённые модели, число активных ключей и срок действия. Подключение может видеть, изменять и отзывать только созданные им ключи. Отозвать приложение можно в разделе «Агенты и MCP» — его tokens и активные ключи будут отключены.

Ручное подключение

Создайте scoped zpm_ в dashboard и задайте его как bearer-заголовок MCP-клиента. Это account-scoped credential для доверенной автоматизации, а не consent-bounded OAuth grant.

MCP 2026 discovery
curl -X POST https://zapros.ai/mcp -H "Authorization: Bearer zpm_ваш_management_токен" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: server/discover" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "my-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}'

Методы: server/discover, ping, tools/list и tools/call. Доступные tools фильтруются scopes токена: профиль, модели, estimate, ключи, usage и read-only compute discovery.

Для мутаций используются отдельные scopes keys:create, keys:update и keys:revoke. MCP никогда не возвращает сырой новый zpr_ в вывод модели: вместо него приходит dashboard-ссылка для владельца аккаунта. В течение 15 минут Reveal можно безопасно повторить; после сохранения ключа владелец подтверждает получение. Без подтверждения claim истечёт и ключ будет отключён. Выдавайте только действительно нужные scopes. Платежи, пополнения, создание zpm_ и compute-мутации через MCP намеренно недоступны.

CPU/GPU-ресурсы

Scope compute:read, REST endpoints и MCP tools уже дают стабильный read-only контракт для будущей аренды CPU/GPU. Пока hosting не запущен, пустой список offers или instances — корректный успешный ответ. Создание, остановка и списания ещё не опубликованы.

Ошибки

Ошибки возвращаются со стандартными HTTP-кодами и JSON-телом:

Формат ошибки
{
  "error": {
    "message": "Insufficient balance. Please top up your account",
    "type": "insufficient_funds",
    "code": "insufficient_balance"
  }
}
КодОписаниеРешение
401Неверный API-ключПроверьте ключ в заголовке Authorization
402Недостаточно средствПополните баланс в личном кабинете
404Модель не найденаПроверьте идентификатор модели на странице /models
429Превышен лимит запросовСнизьте частоту (лимит 200/мин на ключ)
500Внутренняя ошибкаПовторите позже. Если повторяется — напишите в поддержку

Примеры кода

Python (OpenAI SDK)

python
from openai import OpenAI

client = OpenAI(
    api_key="zpr_ваш_ключ",
    base_url="https://zapros.ai/api/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-5-nano",
    messages=[{"role": "user", "content": "Привет!"}]
)
print(response.choices[0].message.content)

JavaScript (fetch)

javascript
const response = await fetch("https://zapros.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer zpr_ваш_ключ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-5-nano",
    messages: [{ role: "user", content: "Привет!" }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

Машинные спецификации

Нужна помощь? Напишите в Telegram или на support@zapros.ai

Получить API-ключ