README.md

OpenAI-Compatible Gateway on Val Town

A production-ready OpenAI-compatible API gateway whose upstream engine is Val Town's native AI (std/openai → the ValTownOpenAI proxy, authenticated by the ambient valtown token). No external API key required — Cline, Roo Code, Cursor, the Python OpenAI SDK, or cURL can all connect to this gateway and chat through real SSE streaming.

Quick start

  • Base URL: {origin}/api/provider/v1
  • Model: gpt-5.4-nano (Val Town native)
  • API Key: shown in the UI (stored server-side in PROVIDER_API_KEY)

Cline / Roo Code / Cursor (OpenAI-compatible provider)

baseUrl  = {origin}/api/provider/v1
apiKey   = <the key shown in the UI>
modelId  = gpt-5.4-nano

cURL

curl {origin}/api/provider/v1/chat/completions \
  -H "Authorization: Bearer <KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-nano","stream":true,
       "messages":[{"role":"user","content":"مرحباً"}]}'

Endpoints

MethodPathAuthDescription
GET/healthno{status:"ok", service:"internal-bridge"}
GET/api/provider/v1noService info & limits
GET/api/provider/v1/modelsnoActive model, OpenAI format
POST/api/provider/v1/chat/completionsyesChat (SSE or non-streaming)
GET/api/provider/configno{model, apiKey, keyRequired} for the UI

Architecture

  • main.ts (http) — router: mounts the gateway under /api/provider/v1, serves the RTL frontend and assets.
  • lib/bridge.ts (script) — the internal provider bridge: sanitizeMessages (never throws), max_tokens clamping, auto-healing singleton that re-reads platform credentials, and real SSE streaming via the OpenAI SDK.
  • public/ — Arabic RTL UI (playground, connection info, integration snippets, activity/usage).

Environment variables

  • PROVIDER_API_KEY — the gateway bearer key (required on chat completions).
  • PROVIDER_MODEL — optional, overrides the default gpt-5.4-nano.

Notes & limits

  • Native engine rate limit: ~10 requests/minute (Val Town proxy).
  • Pro users get 10 expensive-model requests per rolling 24h, then bump to nano.
  • max_tokens is auto-clamped to the engine ceiling to avoid upstream errors.