Setup

1. Install the client

Install the same package you will use later for routing, environments, traces, and benchmarks:

pip install plural

2. Create a workspace key

1. Open API Keys in the workspace that should own the traffic.
2. Create a named key and copy it once.
3. Export it as PLURAL_API_KEY. The client reads that variable automatically. Existing enroute_ keys still authenticate.

3. Send a request

Choose a primary model and an optional fallback. The response tells you which model and provider actually served the request, plus token usage and cost.

from plural import Plural, Message

client = Plural(
    base_url="https://api.pluralintel.com/v1",
)
response = client.chat(
    model="openai/gpt-5.6-luna",
    messages=[Message(role="user", content="Hello from Plural")],
    models=["anthropic/claude-sonnet-5"],
)
print(response.text)
print(response.model, response.usage.cost)
client.close()

4. Confirm the result

Open Traces. The request should appear as a production trace, and its cost should appear in workspace usage. If the wallet is empty, add credits before retrying. The client also appends a metadata-only local trace to .plural/traces.jsonl by default; content capture stays off until you opt in.

Hosted gateway or your own provider keys

The code above sends traffic through Plural and bills the workspace wallet at the upstream list price. Use Plural(providers=...) when provider credentials must stay in your process. Both modes use the same request, response, tracing, and evaluation APIs, so you can change the deployment boundary without rewriting the application.