Chat completions
POST /v1/chat/completions on the process that runs cosmos_pay_gateway.py. This page does not name a public API host. The buyer key is the Authorization: Bearer header only. See Auth and Errors.
Request
The body is JSON. A body that does not parse is 400 bad_json, before this path. A missing or unknown bearer is 401 bad_key with message unknown or revoked key, and the stream does not start. An empty messages array fails later, inside chat_request: the JSON path returns 502 upstream_failed with message request refused, and the pool stream writes data: code upstream_failed with no [DONE].
model is required. If it is missing, the response is 400 missing_model with message model parameter is required. messages must be present and must be an array. Otherwise the response is 400 missing_messages with message messages array is required. An empty array passes that check.
stream must be the JSON boolean true to select server-sent events. A string, a number, or an omitted field takes the single JSON response.
An id that contains /, or ends with :free, uses the OpenRouter key pool. That path does not call RunPod. Any other id uses the registry rail for that model.
Pool body
For a pool id, cosmos_pay_or_usage.chat_request builds the upstream object. It always has model, messages, stream (the boolean for this branch, not a copy of a non-boolean client value), and usage set to {"include": true}. The gateway passes that boolean itself. An empty model is already 400 missing_model and does not reach this builder.
passthrough then copies allowlisted keys that are present on the client body. Values are not rewritten. A missing allowlisted key is omitted, not stored as null. Every other client key is ignored, including messages, stream, and any API key field. messages on the upstream body are the ones chat_request already set.
toolstool_choiceresponse_formatproviderreasoningpluginsmodelstemperaturetop_pmax_tokensmax_completion_tokensstopseedfrequency_penaltypresence_penaltymodalities
max_prompt_tokens is not allowlisted. It only caps the reserve, and it defaults to 256 when absent. max_completion_tokens, or else max_tokens, caps the completion side of the reserve and also defaults to 256. Those two names are forwarded when the client sent them. The reserve cap is separate from the forwarded value.
The pool callβs upstream headers are HTTP-Referer: https://tokenctr.com, X-Title: TokenCenter, Content-Type: application/json, and Authorization for the leased lane key. That key is not written into the JSON body, and it is not the buyer key.
One JSON response
On the pool path a 200 body is the upstream object, with api_key, authorization, and Authorization removed if they were present. Headers on that response are x-cosmos-credit-balance and x-cosmos-quota-reset. The pool path does not set x-cosmos-quota-remaining.
A numeric usage cost, including 0, is measured dollars. A missing or non-numeric cost is UNPRICED: the reserve is refunded, and zero is not stored as the price. A free-lane model with no free-lane key is 503 and code free_lane_unconfigured (message free lane has no key). It does not borrow the paid key and it does not call RunPod. No supply is 503 no_supply. An unknown catalog price is 503 with the charge code catalog_unknown (message model price is unknown). A failed reserve is 402 reserve_denied. A daily cap miss is 429 cap. Upstream HTTP 429 cools that key and tries one other key in the same lane; if that also fails the code is 429 lane_saturated. Any other upstream HTTP status is returned as that status with code upstream_failed. Lanes are not crossed.
Before the model is chosen, the JSON path also rate-limits: 60 requests in 60 seconds per key, and 120 per client IP. The status is 429, Retry-After is 60, the code is rate_limit_exceeded_key or rate_limit_exceeded_ip, and the message is Rate limit exceeded (60 requests/minute). Please back off.
A non-pool id that is not in the registry is 503 no_supply with message model '<id>' not in the registry. A rail exception is 502 rail_error. A free plan with no credits and no remaining free quota is 429 quota_exhausted. A failed credit reserve on that path is 402 insufficient_credits. A key daily cap that is already spent is 429 key_cap_exhausted. Those non-pool JSON responses also send x-cosmos-credit-balance and x-cosmos-quota-reset. x-cosmos-quota-remaining is set on the free zero-credit path.
Streaming and delta.content
Boolean stream: true answers 200 immediately with Content-Type: text/event-stream, Cache-Control: no-cache, and Connection: keep-alive. Later failures are data: lines on that response. They are not a second HTTP status. Auth has already passed, so a bad bearer never opens this stream.
On the pool path each upstream SSE JSON object is copied through as its own data: line. The gateway does not move fields. Incremental text, when the upstream object has it, is choices[0].delta.content. Read that field. It is not copied to another name.
The bill keeps prompt_tokens, completion_tokens, and cost from the last usage object. A string id on an object is the generation id. A numeric cost, including 0, is measured. A missing or non-numeric cost is UNPRICED, the reserve is refunded, and zero is not stored as the price. An upstream line data: [DONE] is not forwarded. After the objects are settled the gateway writes one data: [DONE].
Pool stream errors are data: {"error":{"code":...}} and that return does not write [DONE]. Codes this path yields: cap; 503 with message free_lane_unconfigured or another no-supply code, or with the charge code such as catalog_unknown; 402 when the reserve fails; 429 with message lane_saturated; upstream_failed. One lease covers the whole stream. A 429 from upstream retries once, in the same lane only.
If the limiter refuses after the 200 has started, the line is data: with code rate_limit_exceeded_key or rate_limit_exceeded_ip and message Rate limit exceeded, and there is no [DONE].
A non-pool id is different. Each object the rail yields is JSON-encoded as one data: line. Text is whatever that object contains. This page does not add delta.content when the rail did not yield it. A yielded object that has usage is the usage used at settle. Success then writes data: [DONE]. A missing model is data: code no_supply and message model '<id>' not in registry. A failed reserve is code insufficient_credits. An empty free quota is code quota_exhausted. A rail exception refunds a reserve and sends code stream_error. Those returns do not add [DONE].