Developer Documentation · HalveCost-API

1) Quick Start

Base URL (local): http://127.0.0.1:8000
Auth: Authorization: Bearer <YOUR_PROXY_API_KEY>
OpenAI Chat: /v1/openai/chat/completions
OpenAI Responses: /v1/openai/responses
Anthropic Messages: /v1/anthropic/messages
See pricing: /docs/pricing

2) Getting Your Proxy API Key

Dashboard → Settings → API Keys → Create new key → Copy and store securely.

Place your screenshot at /public/images/api-key.png.

3) What Your API Key Is Used For

Authenticate to the proxy (Authorization: Bearer <key>).
Attribute usage to your user (billing, logs, alerts).
Enforce balance/quotas – returns 402 if insufficient credits.
Trigger alerts & limits (Redis daily counters, email alerts, auto-pause).
Never forwarded upstream – upstream provider keys are stored server-side.

4) Base URLs & Endpoints

General: /v1/{provider}/{endpoint}
OpenAI Chat → /v1/openai/chat/completions
OpenAI Responses → /v1/openai/responses
Anthropic Messages → /v1/anthropic/messages
OpenAI clients often take base_url = http://127.0.0.1:8000/v1/openai

5) Authentication & Headers

Authorization: Bearer YOUR_PROXY_API_KEY
Content-Type: application/json
Streaming: Accept: text/event-stream

6) Examples

curl — OpenAI Chat (non-streaming)

curl -X POST "http://127.0.0.1:8000/v1/openai/chat/completions" \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"Tell me a joke."}],
    "max_tokens": 50
  }'

curl — OpenAI Chat (streaming)

curl -N "http://127.0.0.1:8000/v1/openai/chat/completions" \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type": "application/json" \
  -H "Accept": "text/event-stream" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"Stream a tiny haiku."}],
    "stream": true
  }'

Python (requests) — OpenAI Chat

import os, requests
BASE_URL = os.getenv("BASE_URL", "http://127.0.0.1:8000")
API_KEY = os.getenv("APP_API_KEY")
url = f"{BASE_URL}/v1/openai/chat/completions"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
payload = {"model": "gpt-4o", "messages": [{"role":"user","content":"Tell me a joke."}]}
r = requests.post(url, headers=headers, json=payload, timeout=60)
print(r.status_code, r.json())

Node (fetch) — OpenAI Chat (streaming)

const BASE_URL = process.env.BASE_URL || "http://127.0.0.1:8000";
const API_KEY = process.env.APP_API_KEY;
const res = await fetch(`${BASE_URL}/v1/openai/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Accept": "text/event-stream",
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Stream a tiny haiku." }],
    stream: true,
  }),
});
for await (const chunk of res.body) process.stdout.write(chunk.toString());

LangChain (Python) — OpenAI-compatible

from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage
llm = ChatOpenAI(base_url="http://127.0.0.1:8000/v1/openai", api_key="YOUR_PROXY_API_KEY", model="gpt-4o")
msgs = [SystemMessage(content="Be brief."), HumanMessage(content="One-line proxy joke.")]
print(llm.invoke(msgs).content)
for ch in llm.stream(msgs):
    if ch.content: print(ch.content, end="")

7) Streaming (SSE)

Set stream: true and send Accept: text/event-stream. The proxy forwards SSE lines unchanged and captures final usage when upstream includes it.

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"!"}}]}

data: [DONE]

8) Usage & Billing

Usage parsed for OpenAI (prompt_tokens, completion_tokens) and Anthropic (input_tokens, output_tokens).
Cost = (tokens_in × in_price + tokens_out × out_price)/1e6 × user.rate_multiplier × per-model multiplier.
Balance checks before/after; insufficient funds → 402.
Daily counters in Redis; one-per-day email alerts; provider auto-pause on stop threshold.

9) Error Handling & Troubleshooting

400 Unknown model pricing — model id not recognized in model_catalog.json.
402 Insufficient credit balance — top up or lower max_tokens.
429 ... paused — provider paused; admin can reactivate.
503 No active API keys — add provider key(s) in Admin.
5xx Proxy error — for SSE ensure stream: true + Accept: text/event-stream.

10) Security Best Practices

Treat your Proxy API Key like a password; never commit it.
Use env vars locally (e.g., APP_API_KEY) & secret managers in prod.
Rotate keys regularly; revoke immediately if compromised.
Use separate keys per app/service for least privilege.