API Documentation

Introduction

All requests go to a single base URL. Endpoints mirror the OpenAI API shape, so existing SDKs and tools work with a one-line change.

• Authenticate with a Bearer API key (prefix mdb_live_).
• Send and receive JSON; streaming uses server-sent events.
• Pick any model by passing its identifier in the model field.
• Every billable response reports its cost and your balance in headers.

Quickstart

1. Create an account and grab your key from the dashboard. 2. Add credit. 3. Make your first call:

curl https://modeldatabase.com/v1/chat/completions \
  -H "Authorization: Bearer $MDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4-8",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://modeldatabase.com/v1",
    api_key="mdb_live_...",
)

resp = client.chat.completions.create(
    model="anthropic/claude-opus-4-8",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://modeldatabase.com/v1",
  apiKey: "mdb_live_...",
});

const resp = await client.chat.completions.create({
  model: "anthropic/claude-opus-4-8",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

Authentication

Every request to /v1/* must include your API key as a Bearer token. Keys are created — and can be labelled, rotated, or revoked — from your dashboard. A key is shown only once at creation; store it securely.

Authorization: Bearer mdb_live_xxxxxxxxxxxxxxxxxxxx

Chat completions

The core endpoint. Request and response bodies match the OpenAI Chat Completions schema.

Request body

Other standard OpenAI parameters (top_p, stop, presence_penalty, …) are passed through to the underlying model when supported.

Example response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "anthropic/claude-opus-4-8",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 7, "total_tokens": 16 }
}

Streaming

Set "stream": true to receive the response token-by-token as server-sent events. Each event is a data: line carrying a JSON chunk; the stream ends with data: [DONE].

curl -N https://modeldatabase.com/v1/chat/completions \
  -H "Authorization: Bearer $MDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4-8",
    "messages": [{"role":"user","content":"Stream a haiku"}],
    "stream": true
  }'

# data: {"choices":[{"delta":{"content":"Silent"}}]}
# data: {"choices":[{"delta":{"content":" code"}}]}
# data: [DONE]

List models

Returns the catalog of models you can call, in OpenAI list format.

curl https://modeldatabase.com/v1/models \
  -H "Authorization: Bearer $MDB_API_KEY"

Health

A public, unauthenticated liveness check — useful for uptime monitors.

Response headers

Every successful billable call returns two headers so you can track spend in real time — no extra API call required.

Errors

Errors use standard HTTP status codes with a JSON body containing a detail field.

Capabilities

The endpoint is a faithful OpenAI-compatible proxy, so the features you already use pass straight through to whichever model you select:

• Streaming — set "stream": true for server-sent events.
• Tool / function calling — send tools and tool_choice; supported models return tool_calls.
• Structured output / JSON mode — pass response_format to models that support it.
• Vision — send image content parts to multimodal models.

Rate limits

We don't impose a fixed per-minute request limit today — throughput is governed by fair use and by the upstream provider's own limits for the model you call. Two safeguards protect your balance:

• Per-request cost cap — any single call whose upstream cost would exceed a safety threshold is rejected with 402 before it runs, so a runaway prompt can't drain your balance.
• Prepaid balance — when your credit reaches zero, billable calls return 402 Payment Required until you top up.

Billing & credits

Model Database is prepaid and usage-based. Buy a credit pack ($10, $50, or $200) from your dashboard — with a card via Stripe, or in crypto (BTC, ETH, or USDT). Each request draws down your balance at the model's token rates. Credit never expires, and you can top up at any time.

See Pricing for the full breakdown, or head to your dashboard to add credit and view usage history.