`POST /v1/chat/completions`

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

bash

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 (chat)

Chat with stream: true 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 (chat 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 chat 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]:

json

{"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}.

`POST /v1/responses`

Stateless Responses facade for clients that POST {base_url}/responses. Same Bearer key, prepaid debit, catalog, and fall-forward as chat. store and previous_response_id are not persisted. GET /v1/responses and GET /v1/responses/{id} stay 404.

bash

curl -sS -X POST "https://api.pzero.studio/v1/responses" \
  -H "Authorization: Bearer pzero_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b",
    "input": "Hello",
    "stream": true
  }'

Streamed events use full response.* names on both the event: line and JSON type. There is no chat [DONE] and no pzero.cost frame.

Success after settle: response.completed with nested response (id, usage as input_tokens / output_tokens / total_tokens) plus flat metadata costUsdc, clearingPriceCents, supportReference.
Billed incomplete: response.incomplete with the same cost metadata. The usage key is absent.
Settle failure: response.failed with nested response.status: failed and no response.error.

Buffered Responses use the same X-Pzero-* cost headers as buffered chat.

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.

POST /v1/chat/completions ​

What a call cost ​

Streaming (chat) ​