API Documentation

Sage inference proxy — OpenAI-compatible chat completions with passkey auth, usage tracking, and credit-based rate limiting.

Overview

Sage is an AI inference proxy deployed as a Cloudflare Worker. It provides OpenAI-compatible /v1/chat/completions and Anthropic-compatible /v1/messages endpoints, proxying requests to DeepSeek, OpenAI, Anthropic, and Groq based on the model name. The chat endpoint auto-detects modality — text, vision, image generation, TTS, and sound effects — routing to the right model without client-side model selection. Authentication uses WebAuthn passkeys (Touch ID, Face ID, security keys) with session cookies and API keys.

Base URL: https://sage-api.devblocktechnologies.com

Provider Routing

Sage automatically routes your request to the correct upstream provider based on the model field in the request body.

Modality Auto-Detection

The /v1/chat/completions endpoint auto-detects non-text modalities from your messages — no separate endpoints needed. Send a regular chat message and Sage routes to the right backend automatically.

The response comes back in standard chat.completion JSON format with the generated media as a data URI or descriptive markdown. You can still use the explicit /v1/images/generations, /v1/audio/speech, and /v1/audio/generation endpoints for fine-grained control.

Models & Pricing

Sage offers a credit-based pricing model. Each model has a per-request credit cost. See the billing page for current credit bundles.

POST /v1/images/generations Public

Generate images from text prompts. Powered by Cloudflare Workers AI using Stable Diffusion XL Lightning. Requires API key auth. Free tier: 10k neurons/day. 0.5 credits per generation.

curl -X POST https://sage-api.devblocktechnologies.com/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cf/stable-diffusion-xl-lightning",
  "prompt": "A serene mountain lake at sunset",
  "n": 1
}'

{
  "data": [
    { "url": "https://..." }
  ]
}

POST /v1/images/analysis Public

Analyze images using vision models. Powered by Cloudflare Workers AI (Mistral Small 3.1 24B). Uses the OpenAI vision format — pass image_url content parts in messages. Requires API key auth. 0.5 credits per analysis.

curl -X POST https://sage-api.devblocktechnologies.com/v1/images/analysis \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cf/mistral-small-3.1-24b",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this image?" },
        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
      ]
    }
  ]
}'

{
  "id": "chatcmpl-...",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "The image shows a mountain range..."
    }
  }]
}

POST /v1/audio/speech Public

Convert text to speech. Powered by ElevenLabs (Adam voice, eleven_multilingual_v2). Returns an audio/mpeg binary stream. Requires API key auth. 1 credit per request.

curl -X POST https://sage-api.devblocktechnologies.com/v1/audio/speech \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
  "input": "Hello, welcome to Sage Inference API.",
  "voice": "adam",
  "model": "eleven_multilingual_v2"
}' \
  --output speech.mp3

Binary audio stream (audio/mpeg)

POST /v1/audio/generation Public

Generate sound effects from text descriptions. Powered by ElevenLabs sound generation API. Returns an audio/mpeg binary stream. Requires API key auth. 1 credit per request.

curl -X POST https://sage-api.devblocktechnologies.com/v1/audio/generation \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Rain falling on a tin roof with distant thunder",
  "duration_seconds": 5
}' \
  --output effect.mp3

Binary audio stream (audio/mpeg)

POST /v1/audio/transcriptions Public

Transcribe speech to text. Powered by Cloudflare Workers AI (OpenAI Whisper). Accepts multipart/form-data with an audio file or JSON with base64-encoded audio. Requires API key auth. 0.5 credits per transcription.

curl -X POST https://sage-api.devblocktechnologies.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-..." \
  -F "file=@speech.mp3"

curl -X POST https://sage-api.devblocktechnologies.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
  "audio": "//uQx...base64...",
  "model": "whisper-1"
}'

{
  "text": "Hello, this is a test of the transcription service."
}

Error Codes

Sage returns standard HTTP status codes and JSON error responses.

Device Codes

Use device codes to authenticate desktop and CLI applications. Generate a code from your dashboard and enter it in the app.

# From the dashboard, click "Generate device code"
# Enter the 8-character code in your desktop app:
sage auth ********

GET /health Public

Health check endpoint. Returns database connectivity status.

curl /health

Response

{"ok":true,"uptime":1712345678000}