Документация API
Полное руководство по интеграции с API zapros.ai
https://zapros.ai/api/v1
API совместим с OpenAI — подставьте этот base_url в любой OpenAI-совместимый SDK, и всё заработает.
Быстрый старт
Начните использовать API zapros.ai за 3 простых шага:
Зарегистрируйтесь
Создайте аккаунт на zapros.ai/register. Понадобится только email и пароль.
Получите API-ключ
В личном кабинете перейдите в раздел API-ключи и создайте новый ключ. Он будет иметь вид zpr_xxx...
Сделайте первый запрос
Пополните баланс и вызовите API. Пример ниже:
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.
Запрос
{
"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 // Макс. кол-во токенов в ответе
}top_p, stop, tools (function calling), tool_choice, response_format и другие. Поддержка конкретного параметра зависит от модели.Ответ
{
"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. Поддерживает обычные и потоковые ответы.
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-проходы, возможная доплата модели и выбранный поисковый движок.
{
"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
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. Можно передать одну строку или пакет строк; тарифицируются входные токены.
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} ключом того же аккаунта. Видео тарифицируется посекундно; стоимость зависит от модели, длительности и поддержки аудио.
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:
data: {"choices":[{"delta":{"content":"Привет"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"!"},"finish_reason":null}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]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
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).
Получить список моделей программно:
curl https://zapros.ai/api/v1/models \
-H "Authorization: Bearer zpr_ваш_ключ"Этот endpoint возвращает модели для Chat Completions и Responses. Каталог эмбеддингов доступен отдельно:
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-токены, пополнять баланс или управлять платежами.
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/tokenaccount: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. Оценка использует текущие цены каталога, не вызывает провайдера, не резервирует баланс и ничего не списывает; фактическая стоимость принятого запроса может отличаться.
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 без секрета; мутации записываются в аудит.
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/instancesMCP для агентов
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 — ограниченную динамическую регистрацию публичного клиента.
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/tokenAccess token zpo_ обычно живёт 15 минут. Refresh token ротируется при каждом обмене; повторное использование старого refresh token отзывает весь MCP grant. Этот токен предназначен только для MCP. Для Management REST нужен отдельный OAuth grant с resource=https://zapros.ai/api/v1/management; audiences не взаимозаменяются.
Ручное подключение
Создайте scoped zpm_ в dashboard и задайте его как bearer-заголовок MCP-клиента. Это account-scoped credential для доверенной автоматизации, а не consent-bounded OAuth grant.
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.
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)
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)
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-ключ
zapros.ai