Documentation

Build in minutes

An OpenAI-compatible API. Point your SDK at the gateway, drop in your key, and start streaming.

Quickstartcopy any snippet and run it

curl https://mappace.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in one sentence."
    }
  ],
  "stream": true
}'

Product Guide

Using the Mappace console

01Create your account

02Add credits

Top up any amount (USD).

Billing →

03Create an API key

Generate a key and copy it once.

API Keys →

04Pick a model

Browse prices and copy a model id.

Models →

05Send a request

Point your OpenAI SDK at the gateway and go.

API reference →

06Watch usage

Track spend by model on the analytics page.

Usage →

Overview

Mappace is a pay-as-you-go LLM gateway. One OpenAI-compatible endpoint, one API key, and a credit balance — no tiers, no subscriptions, no monthly plans. You add credits once, then every request deducts exactly the model's underlying price for the tokens you use. There is no markup: what the model costs, you pay. When your balance runs low, you top up any amount.

Everything is priced in USD cents under the hood; your balance is always stored as credits, and what you see is the dollar cost of each token you use.

Dashboard

Your account at a glance. The top cards show your credit balance and the last 24 hours of activity — requests, tokens, and spend. Sparklines show recent trends, and a feed lists your latest calls across every model. Open it from the sidebar whenever you want a quick read on account health or to catch abnormal usage early. Open Dashboard →

Best used as a daily pulse check: is spend where you expect it to be? Any spike in requests usually shows here first.

Models

Browse every model Mappace can route to. Search by name, compare input and output price per million tokens (with any active promo struck through), and copy a model id straight into your code or a test. Prices update from the provider catalog, so what you see is what you pay. Open Models →

Before you integrate, spend two minutes here: the right model choice is usually the biggest cost lever you have.

API Keys

Create the key you'll send with every request. Give it a clear name (by project or environment), and you can revoke it at any time — revocation is instant, so a leaked key stops working immediately. Keys are shown once at creation; copy and store them like a password. Never embed a key in client-side code. Open API Keys →

Create one key per project or service. Separate keys make auditing, rate debugging, and access control dramatically easier — you can revoke one without touching the others.

Request Logs

Every call is recorded here: model, tokens, status, latency, and cost. Filter by key, model, or time to troubleshoot a failure, reconcile spend, or just see what's running. Logs are yours — delete a single row, or clear your whole history, whenever you like. Nothing is kept longer than you want it. Open Request Logs →

When a request fails or a charge looks wrong, this is the first place to look. And because you can delete individual rows or wipe everything, your request history is fully under your control.

Billing & Top-ups

Your balance and top-up history live here. Add credits in any amount in US Dollars. Recent transactions list every top-up and deduction so you can see exactly where credits went. Keep the balance above your typical daily spend to avoid interruptions. Open Billing →

Recharge before you hit zero, not after. A topped-up balance means your app keeps running through traffic spikes instead of 402-ing mid-request.

Usage Analytics

The cost view. See totals and trends, break spend down by model, and watch an hourly time series of tokens and cost over the last week. It's the page to answer 'which model is eating my budget?' and to spot a runaway loop before it drains the balance. Open Usage Analytics →

Make /usage a habit after a launch. A single misconfigured retry can quietly 10x a model's share of your bill — the by-model breakdown surfaces it fast.

Pricing

The pay-as-you-go explainer and the place to top up. No plans to compare, no fine print — just the model prices and your balance. Credits never expire and aren't bundled into a tier, so pricing stays transparent: you pay only for what you use. Open Pricing →

Settings

Account and preference controls: profile, theme, and notification toggles. Everything in the console — balances, model prices, usage — is shown in US dollars, since credits are priced in USD cents. Open Settings →

API Reference

Endpoints

Base URL

https://mappace.com/v1

Authentication

Authorization: Bearer YOUR_API_KEY

Authentication

Every request is authenticated with a bearer token. Create an API key from the dashboard, then send it as an Authorization header. Keys are scoped and can be revoked at any time. Treat a key like a password — never ship it in client-side code.

export MAPPACE_KEY="sk_live_..."

curl https://mappace.com/v1/models \
  -H "Authorization: Bearer ***"

Chat CompletionsPOST/v1/chat/completions

The core endpoint. It speaks the standard OpenAI request/response shape, so your existing OpenAI SDK works unchanged — just point the base URL at the gateway. Turn on streaming with stream: true to receive tokens as they are generated. All common request options (n, logprobs, parallel_tool_calls, logit_bias, tools, stream_options) are forwarded to the model.

curl https://mappace.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in one sentence."
    }
  ],
  "stream": true
}'

Parameter	Type	Required	Description
model	string	Yes	Model id to use (see /v1/models for the full list).
messages	array	Yes	Conversation history in OpenAI message format (role + content).
stream	boolean	No	Stream tokens as they generate instead of one response.
temperature	number	No	Sampling temperature (0-2); higher is more random.
max_tokens	integer	No	Upper bound on generated tokens (reasoning + content).
top_p	number	No	Nucleus sampling; an alternative to temperature.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1755504000,
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Quantum computing uses qubits that can be 0 and 1 at once." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 22, "total_tokens": 40 }
}

Request Options

These optional fields let you shape the model's output without changing your SDK. n returns multiple completions; logprobs/top_logprobs expose how confident the model was per token (great for search ranking and evals); parallel_tool_calls lets the model run several tools at once or forces one-at-a-time; logit_bias nudges word choices; stream_options toggles usage stats in a stream. Pass them in the request body like the example.

{
  "model": "kimi-k3",
  "messages": [{ "role": "user", "content": "Pick the best city." }],
  "n": 2,
  "logprobs": true,
  "top_logprobs": 3,
  "parallel_tool_calls": true,
  "logit_bias": { "1234": -5 },
  "stream_options": { "include_usage": true }
}

List ModelsGET/v1/models

Returns every model the gateway can route to, in the standard OpenAI shape. Each entry also carries capability tags — context window, supported modalities (text/vision/audio), tool support, and pricing — so your app can pick the right model automatically instead of hard-coding ids.

curl https://mappace.com/v1/models \
  -H "Authorization: Bearer ***"

RerankPOST/v1/rerank

Given a query and a list of documents (or passages), the rerank endpoint returns them best-first by relevance. This is the missing piece for search and RAG (retrieval-augmented generation): you fetch candidate chunks, then rerank them so the most useful ones reach the model. Pass the model id from /v1/models, or omit it to use the provider default.

curl https://mappace.com/v1/rerank \\
  -H "Authorization: Bearer ***" \\
  -H "Content-Type: application/json" \\
  -d '{
  "query": "best sci-fi novel",
  "documents": ["Dune", "A baking cookbook", "The Expanse"]
}'

ResponsesPOST/v1/responses

The modern, streaming-native way to call a model. It wraps chat with built-in tool use and a cleaner state model, and is what many new SDKs target by default. If your client speaks the Responses API, point it at this endpoint and it just works.

curl https://mappace.com/v1/responses \\
  -H "Authorization: Bearer ***" \\
  -H "Content-Type: application/json" \\
  -d '{
  "model": "kimi-k3",
  "input": "Summarize the meeting notes."
}'

ModerationsPOST/v1/moderations

A content-safety check: send text in, get back whether it looks unsafe (hate, violence, self-harm, sexual, etc.). Useful before you display user-generated content, or to satisfy platform/app-store requirements. Returns per-category scores you can threshold yourself.

curl https://mappace.com/v1/moderations \\
  -H "Authorization: Bearer ***" \\
  -H "Content-Type: application/json" \\
  -d '{ "input": "Text to check for safety." }'

BatchesPOST/v1/batches

Run a large number of requests asynchronously and cheaper than live calls. Upload a batch file first (see Files), then create a batch that references it. Results land in your account when ready — ideal for ETL, dataset labeling, and overnight jobs.

curl https://mappace.com/v1/batches \\
  -H "Authorization: Bearer ***" \\
  -H "Content-Type: application/json" \\
  -d '{ "input_file_id": "file-abc123" }'

FilesPOST/v1/files

Upload files (documents, images, batch inputs) for use with Batches and other endpoints. Send a standard multipart/form-data upload; the file is forwarded to the provider and you get back a file id to reference later.

curl https://mappace.com/v1/files \
  -H "Authorization: Bearer ***" \
  -F "file=@./input.jsonl" \
  -F "purpose=batch"

Headers & Tracing

Every response echoes an x-request-id you can quote when contacting support so we can find the exact call in the logs. Responses also include token-level rate-limit headers (x-ratelimit-limit / remaining / reset-tokens) so you can budget by tokens, not just by request count.

x-request-id: req_8fK2...
x-ratelimit-limit-tokens: 90000
x-ratelimit-remaining-tokens: 87310
x-ratelimit-reset-tokens: 60

Idempotency

Network hiccups happen. Send an Idempotency-Key header with any non-streaming request and the gateway remembers the result. If you retry with the same key, you get the original answer back instead of being charged or processed twice. Generate one UUID per logical operation.

curl https://mappace.com/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Idempotency-Key: 1f3c-9a2b-4d5e" \
  -H "Content-Type: application/json" \
  -d '{ "model": "kimi-k3", "messages": [{ "role": "user", "content": "Hello" }] }'

Token Efficiency

You're billed for every token you send (input) and receive (output) — including the full conversation history on each request. We wrote a full, beginner-friendly guide with before/after examples: Read the token-efficiency guide →

{
  "model": "kimi-k3",
  "max_tokens": 256,
  "messages": [
    { "role": "system", "content": "Reply in 3 bullets. No preamble." },
    { "role": "user", "content": "Summarize the changelog." }
  ]
}

Errors

Errors follow the standard OpenAI format: a JSON object with an error.code and error.message. Common codes: 401 (bad key), 402 (insufficient credits), 404 (unknown model), 429 (rate limited), 501 (the chosen provider does not support that endpoint), 502/504 (upstream error — the gateway attempts failover automatically).

{
  "error": {
    "code": "ENDPOINT_NOT_SUPPORTED",
    "message": "The endpoint /rerank is not supported"
  }
}