First request

Send a chat completion through the gateway after you have a revealed virtual key.

1. Get a key

1. Sign in to the portal
2. Open Keys → Request key
3. A team admin, org admin or platform admin approves it
4. Open the key and reveal it once — the plaintext zea-… value is shown exactly once

Details: Virtual keys and the Keys screen.

2. Call the gateway

Replace YOUR_ZEALLM_KEY and confirm a model your key can access (see Models or GET /v1/models).

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ZEALLM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"Hello from ZeaLLM"}]
  }'

Python:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ZEALLM_KEY",
    base_url="http://localhost:8080/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello from ZeaLLM"}],
)
print(resp.choices[0].message.content)

More languages: SDK snippets.

3. Read the response headers

Successful calls include ZeaLLM headers you can use for logs and attribution:

Header	Meaning
x-zeallm-request-id	Correlation ID (req_…) — look it up in Request Logs
x-zeallm-model-group	Model group that was actually served
x-zeallm-provider	OPENAI, AZURE_OPENAI or ANTHROPIC
x-zeallm-fallback-from	Original model if a fallback fired

4. Attribute spend (optional)

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ZEALLM_KEY" \
  -H "x-zeallm-customer-id: end-user-123" \
  -H "x-zeallm-tags: cost-center-42,experiment-a" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

See Tags and customers.

If it fails

Status	Code	Typical cause
401	invalid_api_key	Key not revealed, mistyped, or gateway cache stale
403	model_access_denied	Model not in the key's access group
404	model_not_found	No enabled deployment for that model group
429	budget_exceeded / rate_limit_exceeded	A budget or RPM/TPM window is exhausted
502	upstream_unavailable	Provider credential missing or invalid

Full list: Error codes. Local stack issues: Troubleshooting.