Quickstart

Three changes to an existing OpenAI SDK integration: the base URL, the key and the model name.

Base URL

https://padmarouter.com/v1

1 · Install

bash

pip install openai

2 · Send a request

python

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PADMA_API_KEY"],
    base_url="https://padmarouter.com/v1",
)

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

3 · Or let the router choose

Send an auto/* id instead of a model and the gateway scores the models it can reach on quality, price and latency, then forwards to the best fit. You are billed at the rate of the model that answered, and the response says which one that was.

python

res = client.chat.completions.create(
    model="auto/smart",          # or auto/cheap, auto/fast, auto/bangla
    messages=[{"role": "user", "content": "Hello from Dhaka!"}],
)
# The model that answered comes back on the response headers:
#   x-padma-router: auto/smart
#   x-padma-model:  anthropic/claude-sonnet-4

4 · Read the usage headers

Every response carries the metered cost so you can log spend next to your own request IDs. Streamed responses carry the request id and model only — their headers are sent before the token counts exist, so the charge is recorded server-side and appears in Activity.

headers

x-padma-request-id:  req_9fb2a41c8e
x-padma-model:       anthropic/claude-sonnet-4
x-padma-tokens-in:   1284
x-padma-tokens-out:  421
x-padma-cost-bdt:    1.22
x-padma-balance-bdt: 1841.38

Errors & retries

Status	Code	Meaning
401	invalid_api_key	The key is missing, malformed or unknown. Never billed.
402	insufficient_balance	The wallet cannot cover the request. Top up to continue.
404	model_not_found	No such model id. See GET /v1/models for the directory.
429	key_daily_limit	A ceiling you set was reached. Refused before the provider is called.
502	upstream_unreachable	The provider could not be reached. Never billed.
503	model_unavailable	No upstream configured or the route is degraded. Never billed.

Documentation shown here is an abridged prototype. Full reference, SDK guides and error tables ship with the API.