Client Integration

Client Integration

Use this page when a local client or SDK asks for a base URL, API key, model, endpoint, or streaming setting.

The local client key is not the provider key

Provider authentication is owned by config.toml. If a client UI requires an API key field, use a dummy local value there and keep the real upstream key in the selected provider config.

Connect a client

1. 1Start ProxAIRun the local proxy using your runtime config.
2. 2Set the base URLPoint the client at the local Proxy listener, not the upstream provider.
3. 3Pick the endpointThe request path determines the inbound protocol.
4. 4Use a model nameRoutes match the client-facing model before optional upstream_model rewrite.
5. 5Send a small requestVerify routing and error format before using tools or large prompts.

Base URL and endpoints

Client endpoint	Inbound protocol	Use when
/v1/responses or /responses	openai_responses	The client supports OpenAI Responses semantics.
/v1/chat/completions or /chat/completions	openai_chat_completions	The client expects Chat Completions choices[].
/v1/messages or /messages	anthropic_messages	The client sends Anthropic Messages payloads.

API keys

Where	Value	Effect
Client UI or SDK	Any local placeholder if required	Satisfies the client; does not control upstream provider auth.
providers.<name>.api_key	Real upstream provider key	Sent upstream using the provider protocol auth header.
Environment variables	Only if your launcher injects them into config or CLI	ProxAI does not require clients to send provider secrets.

For exact auth behavior, see Behavior Contracts.

Model names and routes

The client-facing model is matched before provider model rewrite:

[[routing.routes]]
request_protocol = "openai_chat_completions"
match_kind = "exact"
model_pattern = "MiniMax-M3-preview"
provider = "minimax"
upstream_model = "MiniMax-M3"

• model_pattern matches what the client sends.
• provider selects the upstream configuration.
• upstream_model is what ProxAI sends to the provider.

See Routing and Providers and Route Matching.

Error format

Use readable text for interactive debugging, and JSON when an SDK expects structured errors:

[error_responses]
format = "json"

See Error Responses.

Streaming clients

Streaming clients should expect protocol-specific terminal signals:

Protocol	Terminal signal
OpenAI Responses	response.completed
OpenAI Chat Completions	[DONE]
Anthropic Messages	message_stop

If a stream stalls after tool-call arguments begin, check [tool_calls].timeout_secs. See Streaming Behavior.

Next pages

Quick StartFirst local run and config setup.Choose a ProtocolDecide inbound and provider protocols.TroubleshootingSymptoms, likely causes, and next checks.CLI ReferenceFlags, route overrides, and capture commands.