API documentation

Base URL & authentication

https://dreamprompting.com/api/v1

Authorization: Bearer YOUR_API_KEY

Chat completions

POST /api/v1/chat/completions — OpenAI-compatible.

Request body

Examples

curl https://dreamprompting.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role":"user","content":"Hello!"}]
  }'

from openai import OpenAI
client = OpenAI(
    base_url="https://dreamprompting.com/api/v1",
    api_key="YOUR_API_KEY",
)
r = client.chat.completions.create(
    model="auto",
    messages=[{"role":"user","content":"Hi"}],
)
print(r.choices[0].message.content)

const r = await fetch(
  "https://dreamprompting.com/api/v1/chat/completions",
  { method:"POST",
    headers:{"Content-Type":"application/json",
             "Authorization":"Bearer YOUR_API_KEY"},
    body: JSON.stringify({
      model:"auto",
      messages:[{role:"user",content:"Hi"}]
    })});
const d = await r.json();
console.log(d.choices[0].message.content);

{
  "object": "chat.completion",
  "model": "openai/gpt-oss-120b",
  "provider": "groq",
  "choices": [{
    "index": 0,
    "message": {"role":"assistant","content":"Hi!"},
    "finish_reason": "stop"
  }],
  "usage": {"total_tokens": 12}
}

The response includes a non-standard provider field and an X-Served-By header telling you which upstream answered.

Model selection & failover

• "auto" (default): the gateway picks a live provider and automatically fails over to the next if one errors or is rate-limited.
• "provider/model": pin a specific model, e.g. "groq/openai/gpt-oss-120b" or "google/gemini-3.1-flash-lite". If it fails, the gateway still falls back to other providers.
• List everything live at /api/v1/models, or browse and test them on the models page.

Streaming (SSE)

Pass "stream": true to receive Server-Sent Events with OpenAI-compatible chat.completion.chunk deltas, terminated by data: [DONE]. The OpenAI SDK's stream=True works unchanged.

curl -N https://dreamprompting.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hi"}],"stream":true}'

Other endpoints

• GET /api/v1/models — list live models.
• GET /api/v1/quota — your remaining rate-limit quota.
• BODY allow_fallback: false — pin the request to the model you named. If it is unavailable you get 503 model_unavailable instead of a different model answering in its place. Needs an explicit model; it means nothing with auto. Useful for a bot that tells its users which model it is.
• BODY identify: false — drop the one-line note we add to the system prompt telling the model which model and provider it actually is. It is there because a model's weights do not record which endpoint is serving them, so without it a Llama answering through Groq will often claim to be ChatGPT. Skipped automatically when you ask for JSON output.
• POST /api/v1/classify — one question, a fixed set of answers. Body: {input, choices}, plus optional model. Returns the chosen label and its index. In practice confidence comes back null today: a probability needs token logprobs, only NVIDIA of our providers reports them, and the models it will actually serve this account are reasoning models whose first token is a thought rather than an answer. The field is there and fills in the moment a provider supports it, and method tells you which way the answer was read. It writes the "reply with one letter" prompt for you, which is where almost all of the speed comes from: measured over 60 questions, an unconstrained prompt took 1,401ms against 142ms for a constrained one. The probability is reported raw and calibrated is always false: on a small model it was 0.896 when right and 0.839 when wrong, so do not threshold on it without checking it against your own labels. See the measurements.
• POST /api/v1/unwatermark — strip watermarks and invisible Unicode from source code and report every removal by codepoint and line. Body: {code}, plus optional trailing, punctuation, homoglyphs and inspect. Costs no tokens. See the invisible character remover.
• POST /api/v1/tokenize — count tokens before you spend them. No API key needed. Body: {text} or {messages}, plus optional encoding and split. See the token calculator.
• POST /api/chat — stateful chat with server-side history (used by the chat page). Body: {seed, message, model?, thinking?}.
• GET /api/chat/history?seed=... — retrieve a chat thread.

Rate limits & budgets

Tokens are the real budget, since that is what the upstream free tiers meter. Requests are a secondary backstop.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Check your remaining budgets any time at GET /api/v1/quota, which reports both requests and tokens, or on your account page. Both 24 hour budgets free up on a rolling window rather than resetting at midnight. Need a higher limit? Just ask and we will raise it, or lift it entirely by adding your own provider key: requests served on a key you supply are routed through your account with that provider and are not counted against this quota.

Errors

Errors use the OpenAI shape and appropriate HTTP status codes:

{"error": {"message": "Rate limit reached (100 requests/minute)...", "type": "rate_limit_error"}}

Common: 400 invalid request, 401 missing/invalid API key, 429 rate limited or daily quota reached, 502 all providers failed, 503 no providers configured.