Model/api/DEVELOPER_API.md

Frox AI Developer API

An OpenAI-compatible developer API with API keys, authentication, rate limiting, and usage tracking, layered in front of the Morph model server.

Developer client  ->  Developer Gateway (:8080)  ->  Morph model server (:8000)
  Bearer frx-...        auth + rate limit + usage        raw /v1 inference

Run

# 1. Start the model server (raw inference, no auth)
python scripts/serve.py --family classic --model ./ckpt --port 8000

# 2. Start the developer gateway in front of it
export MORPH_UPSTREAM_URL=http://localhost:8000
export MORPH_ADMIN_TOKEN=choose-a-strong-admin-secret
uvicorn api.developer_gateway:app --host 0.0.0.0 --port 8080

Issue an API key (admin)

curl -X POST http://localhost:8080/dev/keys \
  -H "X-Admin-Token: $MORPH_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "plan": "pro"}'
# -> { "key": "frx-....", "plan": "pro", "rpm_limit": 120, ... }

The secret is shown once. Store it securely.

Call the API (developer)

Use it exactly like the OpenAI API — just change the base URL and key:

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer frx-...." \
  -H "Content-Type: application/json" \
  -d '{"model": "classic", "messages": [{"role":"user","content":"Hi"}], "stream": true}'

Works with the official OpenAI SDKs:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1", api_key="frx-....")
resp = client.chat.completions.create(
    model="classic",
    messages=[{"role": "user", "content": "Hello"}],
)

Endpoints

Method	Path	Auth	Purpose
POST	/dev/keys	admin	Issue a new API key
DELETE	/dev/keys/{key}	admin	Revoke a key
GET	/dev/usage	key	This key's usage counters
GET	/v1/models	key	List available models
POST	/v1/chat/completions	key	Chat completion (stream or full)
GET	/health	none	Gateway + upstream health

Plans & rate limits

Plan	Requests / min
free	20
pro	120
scale	600

Production notes

• Swap the JSON KeyStore for a real database (interface is small: create, get, revoke, record_usage).
• Set MORPH_ADMIN_TOKEN (without it, key management is open — dev only).
• Restrict MORPH_CORS_ORIGINS to your real client origins.
• Rate limiting is in-memory per process; use Redis for multi-instance.