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-5",
    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-5

4 · Stream the reply

Pass stream=True and tokens arrive as server-sent events, the same chunks the OpenAI SDK already reads.

python

stream = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello from Dhaka!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

5 · 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-5
x-padma-host:        Anthropic
x-padma-tokens-in:   1284
x-padma-tokens-out:  421
x-padma-tokens-cached: 0
x-padma-cost-bdt:    0.81
x-padma-balance-bdt: 1841.38

Errors & retries

Status	Code	Meaning
401	invalid_api_key	The key is missing, malformed or unknown. Never billed.
401	key_expired	The key is past the expiry it was created with. Create a new one.
402	insufficient_balance	The wallet cannot cover the request. Top up to continue.
403	model_not_allowed	The key's guardrail does not allow that model. Never billed.
403	no_allowed_model	Your routing lists or guardrail leave auto/* nothing to choose.
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.
429	rate_limited	More requests in a minute than the key allows. Retry after the Retry-After header.
429	guardrail_daily_limit	A limit from the key's guardrail was reached. Refused the same way.
502	upstream_unreachable	No host serving the model could be reached. Never billed.
503	model_unavailable	No upstream configured or the route is degraded. Never billed.

Padma follows the OpenAI Chat Completions API: anything not covered here works as OpenAI documents it. GET /v1/models lists every model with its prices and the parameters it accepts.