Документация Для Разработчиков

RelayForge AI API

RelayForge AI — это serverless AI gateway playground с единым request-контрактом, free-tier-first маршрутизацией провайдеров, стримингом и нормализованной обработкой ошибок.

Открыть песочницу Открыть статус провайдеров

Обзор продукта

Одна API-поверхность с устойчивым fallback провайдеров.

Основная маршрутизация идет в Groq Free. Free-модели OpenRouter обслуживают fallback. Mock-провайдер гарантирует работоспособность публичного демо даже при недоступности реальных провайдеров.

Поведение стриминга

SSE-события проксируются как нормализованные token-обновления.

Стриминг остается прогрессивным и безопасным для UI. Если провайдер не может корректно стартовать stream, RelayForge переключает запрос на следующий приоритетный уровень до начала вывода.

Модель ошибок

Единая форма для ошибок валидации и апстрима.

Поддерживаются коды: `validation_error`, `provider_timeout`, `provider_rate_limited`, `provider_unavailable`, `malformed_upstream_response`, `stream_interrupted`, `internal_error`, `fallback_activated`.

Справочник endpoint-ов

API-поверхность Worker, доступная статическому frontend.

POST

/api/v1/chat

Нормализованный JSON-ответ с provider-метаданными.

POST

/api/v1/stream

SSE-совместимый endpoint для прогрессивного стриминга токенов.

GET

/api/v1/providers/status

Health-снимок провайдеров и порядок маршрутизации.

GET

/api/v1/logs

История последних запросов с fallback-метаданными.

GET

/api/v1/usage

Агрегаты использования, задержка и распределение провайдеров.

Пример запроса

Типизированный контракт, общий для frontend и Worker.

{
  "prompt": "Explain free-tier fallback strategy",
  "options": {
    "strategy": "auto",
    "stream": true,
    "maxTokens": 512,
    "temperature": 0.35
  },
  "metadata": {
    "source": "relayforge-web"
  }
}

Пример ответа

Каждый успешный ответ содержит нормализованные provider-метаданные.

{
  "success": true,
  "data": {
    "text": "RelayForge first tries Groq Free...",
    "meta": {
      "strategy": "auto",
      "attemptedProvider": "groq",
      "finalProvider": "openrouter",
      "fallbackActivated": true,
      "degradedMode": true,
      "demoMode": false,
      "latencyMs": 842,
      "model": "meta-llama/llama-3.2-3b-instruct:free",
      "timestamp": "2025-01-01T12:00:00.000Z"
    }
  }
}

Примечания по стримингу

POST-стриминг через `fetch` и `text/event-stream`.

Типы событий: `token`, `meta`, `error`, `done`.

Метаданные включают выбранную стратегию, изначальный и финальный провайдер, факт fallback, degraded/demo режим, задержку и модель.

Если stream ломается до первого токена, RelayForge пытается следующий провайдер по приоритету.

Объяснение fallback

Явная оркестрация для надежности на free-tier.

В режиме Auto сначала вызывается Groq.

Timeout, rate-limit, временная недоступность и malformed upstream-ответ переключают запрос на OpenRouter.

Если OpenRouter тоже недоступен или квота закончилась, ответ отдает mock/demo провайдер.

Нормализованный формат ошибки

Ошибки остаются человекочитаемыми и технически корректными без утечки raw stack-trace в UI.

{
  "success": false,
  "error": {
    "code": "provider_rate_limited",
    "message": "Groq Free returned a rate-limit response.",
    "technicalDetails": "HTTP 429 from upstream provider",
    "provider": "groq",
    "fallbackActivated": true,
    "timestamp": "2025-01-01T12:00:00.000Z"
  }
}

RelayForge AI API

{ "prompt": "Explain free-tier fallback strategy", "options": { "strategy": "auto", "stream": true, "maxTokens": 512, "temperature": 0.35 }, "metadata": { "source": "relayforge-web" } }

{ "success": true, "data": { "text": "RelayForge first tries Groq Free...", "meta": { "strategy": "auto", "attemptedProvider": "groq", "finalProvider": "openrouter", "fallbackActivated": true, "degradedMode": true, "demoMode": false, "latencyMs": 842, "model": "meta-llama/llama-3.2-3b-instruct:free", "timestamp": "2025-01-01T12:00:00.000Z" } } }

{ "success": false, "error": { "code": "provider_rate_limited", "message": "Groq Free returned a rate-limit response.", "technicalDetails": "HTTP 429 from upstream provider", "provider": "groq", "fallbackActivated": true, "timestamp": "2025-01-01T12:00:00.000Z" } }