Введение в API

Polza.ai предоставляет REST API, совместимый со стандартом OpenAI, для доступа к сотням AI-моделей.

Базовый URL

https://polza.ai/api

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

Все запросы требуют API-ключ в заголовке Authorization:

Authorization: Bearer YOUR_API_KEY

Получите API-ключ в консоли.

Совместимость с OpenAI

Polza.ai полностью совместим с OpenAI SDK. Просто измените base_url:

from openai import OpenAI

client = OpenAI(
    base_url="https://polza.ai/api/v1",
    api_key="<POLZA_AI_API_KEY>"
)

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://polza.ai/api/v1',
    apiKey: '<POLZA_AI_API_KEY>'
});

Коды ответов

Код	Описание
200	Успешный запрос
201	Задача создана (для асинхронных операций)
400	Неверный запрос
401	Ошибка аутентификации
402	Недостаточно средств или исчерпан лимит расходов, в том числе при параллельных запросах — см. резерв
403	Доступ запрещён, в том числе запрос отклонён модерацией
404	Ресурс не найден
408	Таймаут запроса у провайдера
413	Запрос слишком большой для провайдера
429	Превышен лимит запросов: наш лимит к модели или лимит провайдера — см. повторы
500	Ошибка сервера
502	Провайдер вернул некорректный ответ
503	Провайдер недоступен или нет доступных провайдеров

Формат ошибок

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Провайдер модели ограничил частоту запросов. Повторите через несколько секунд или выберите другую модель.",
    "trace_id": "0b6f1c2e-...",
    "metadata": {
      "provider_name": "OpenAI",
      "raw": "Rate limit reached for requests"
    }
  },
  "trace_id": "0b6f1c2e-..."
}

Поле	Описание
`code`	Машиночитаемый код ошибки: `BAD_REQUEST`, `TOO_MANY_REQUESTS`, `SERVICE_UNAVAILABLE` и т. д.
`message`	Описание ошибки для человека
`trace_id`	Идентификатор запроса — укажите его, когда пишете в поддержку
`metadata`	Необязательно. `provider_name` — провайдер, на котором произошла ошибка; `raw` — исходный текст ошибки провайдера; `reason` — уточнение причины

Повторы запросов

За запрос, который завершился ошибкой, деньги не списываются — в том числе если ошибка пришла посреди стрима. Поэтому ошибку можно безопасно повторить. Исключение — обрыв соединения с вашей стороны (например, по таймауту клиента): уже сгенерированная часть ответа оплачивается, а повтор будет новым запросом. Держите таймаут клиента с запасом, лимит на запрос — 600 секунд. Ключа идемпотентности нет: каждый повтор — отдельный запрос.

Код	Повторять?
408, 502	Да, с паузой
503	Да; если есть заголовок `Retry-After` — не раньше указанного числа секунд
429	Да — см. ниже
402	Только при параллельной нагрузке — короткая пауза и повтор, см. резерв. При нехватке средств или исчерпанном лимите по сумме — нет
400, 401, 403, 404, 413	Нет — исправьте запрос или настройки ключа

Два вида 429

Оба приходят с code: "TOO_MANY_REQUESTS", отличаются заголовком и metadata:

	Наш лимит запросов к модели	Лимит провайдера
Что ограничено	Число запросов к модели в минуту и в сутки на организацию	Частота запросов у провайдера модели
`Retry-After`	Есть: секунды до следующей минуты или до полуночи по Москве	Нет
`metadata`	Нет	`provider_name`, иногда `raw`
Текст	«Достигнут минутный (дневной) лимит запросов к модели. Повторите позже.»	«Провайдер модели ограничил частоту запросов…»
Что делать	Повторить не раньше `Retry-After`	Повторять с нарастающей паузой (1, 2, 4, 8 с) или выбрать другую модель

В наш лимит засчитываются все принятые запросы, включая завершившиеся ошибкой. 429 провайдера доходит до вас, только когда запрос не прошёл ни у одного доступного провайдера модели: переключение между ними мы делаем сами.

Ошибки в стриме

При stream: true ошибка, случившаяся после начала ответа, приходит событием с полем error и finish_reason: "error", а HTTP-статус остаётся 200:

data: {"id":"error_...","object":"chat.completion.chunk","error":{"code":"TOO_MANY_REQUESTS","message":"..."},"trace_id":"...","choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}

data: [DONE]

Так же в стриме приходит 402 при нехватке резерва. Проверяйте поле error в каждом событии.

Лимиты

Параметр	Значение
Макс. размер файла	50 MB
Макс. размер изображения (хранилище)	50 MB
Таймаут	600 секунд

Обзор

Текстовая генерация

Изображения

Медиа

Аудио

Эмбеддинги

Классификация и оценка

Модели

Хранилище

История

Другое

Введение в API

Базовый URL

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

Совместимость с OpenAI

Коды ответов

Формат ошибок

Повторы запросов

Два вида 429

Ошибки в стриме

Лимиты

​Базовый URL

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

​Совместимость с OpenAI

​Коды ответов

​Формат ошибок

​Повторы запросов

​Два вида 429

​Ошибки в стриме

​Лимиты

Базовый URL

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

Совместимость с OpenAI

Коды ответов

Формат ошибок

Повторы запросов

Два вида 429

Ошибки в стриме

Лимиты