POST /v1/chat/completions

OpenAI-compatible text inference. Requires Authorization: Bearer pzero_….

curl -sS -X POST "https://api.pzero.studio/v1/chat/completions" \
  -H "Authorization: Bearer pzero_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

• model: a live text id from GET /v1/models, optional pzero/ prefix.
• messages: standard OpenAI chat array.
• stream: omit or false for buffered JSON; true for SSE.

Buffered success may include X-Balance-Remaining (confirmed USDC). Streams omit cost and balance headers (head written before relay). Both paths send X-Pzero-Request-Id; X-Pzero-Support-Reference when a lookupable attempt row exists.

What a call cost

Tracing (when lookupable):

Header	Meaning
X-Pzero-Request-Id	Per-request id
X-Pzero-Support-Reference	Resolve later at GET /v1/agent/requests/{support_reference}

Cost (buffered 200 only):

Header	Meaning
X-Pzero-Cost-Usdc	What this completion cost
X-Pzero-Clearing-Price-Cents	Posted ask it cleared at

Streaming

With stream: true, PZERO relays SSE. Fall-forward across supplier keys (up to five) happens before any SSE bytes. Usage and [DONE] are withheld until settlement commits. Content chunks may arrive before settlement; cost is final only after the usage chunk and pzero.cost frame (stream) or cost headers (buffered).

If settlement fails after content streamed, you get an SSE error event and no [DONE]. If the stream ends without a final usage chunk (disconnect or upstream truncation), PZERO bills estimated usage (capped at admitted max_tokens and supplier pre-call balance), emits pzero.cost, then an SSE error stream_incomplete with no [DONE].

A stream cannot use cost headers, because the response head is written before the relay starts. Instead one extra frame arrives after the final usage chunk and before [DONE]:

{"object":"pzero.cost","choices":[],"costUsdc":"0.004212","clearingPriceCents":49,"supportReference":"..."}

choices is empty, matching the shape of the final usage chunk, so clients that read choices[0] only when it exists are unaffected. Ignore the frame if you prefer and read the cost later from GET /v1/agent/requests/{support_reference}.

Router behavior (short)

Cheapest eligible offer at or below your max price. One clear per successful completion. See Clearing and Errors for 402, 429, 502, 503, and settle failures.

Next

• POST /v1/image/generate
• POST /v1/video/quote
• Errors & limits