Build with Pied Piper

API reference

Pied Piper exposes an OpenAI-compatible REST API. Anything that speaks the OpenAI wire format works by changing two things: the base URL and the key.

Base URL & auth

Send every request to the /v1 base URL with a bearer key from Settings → Keys.

Field	Type	Description
Base URL		`https://mesh-zeta-eight.vercel.app/v1`
Authorization*		`Bearer sk-pied-piper-…` — your Pied Piper API key.
Content-Type		`application/json` on requests with a body.

Keys are secrets

A Pied Piper key can spend your credits. Keep it server-side, never ship it in client bundles, and revoke + rotate from the Keys page if it leaks.

Create a chat completion

POST/v1/chat/completions

Request body

Field	Type	Description
model*	string	A model slug from the catalog, e.g. `llama-3.2-3b-instruct-q4f32_1`.
messages*	array	Chat history. Each item has `role` (`system` · `user` · `assistant` · `tool`) and `content` — a string, or an array of `text` / `image_url` parts (images as inline `data:` URLs; requests with images route to vision-capable hosts). Up to 200 messages.
stream	boolean	Stream tokens as SSE. Defaults to `false`.
temperature	number	Sampling temperature in `[0, 2]`.
top_p	number	Nucleus sampling in `(0, 1]`.
max_tokens	integer	Max tokens to generate, `[1, 32768]`.
stop	string \| string[]	Up to 4 stop sequences (each ≤ 64 chars).
tools	array	OpenAI-format function definitions. Tool requests route to hosts advertising tool support; the response carries `message.tool_calls` with `finish_reason: "tool_calls"`.
tool_choice	string \| object	`auto` · `none` · `required` · `{type:'function',function:{name}}`.
n	integer	Must be `1` — multiple choices per request aren't supported.

request

1POST /v1/chat/completions HTTP/1.1
2Host: mesh-zeta-eight.vercel.app
3Authorization: Bearer sk-pied-piper-...
4Content-Type: application/json
5
6{
7  "model": "llama-3.2-3b-instruct-q4f32_1",
8  "messages": [
9    { "role": "system", "content": "You are concise." },
10    { "role": "user", "content": "What is Pied Piper?" }
11  ],
12  "temperature": 0.7,
13  "max_tokens": 256,
14  "stream": false
15}

Response

A standard chat.completion object. With stream: true you instead receive a sequence of chat.completion.chunk events with delta fields, ending in data: [DONE].

200 OK

1{
2  "id": "chatcmpl-...",
3  "object": "chat.completion",
4  "created": 1717459200,
5  "model": "llama-3.2-3b-instruct-q4f32_1",
6  "choices": [
7    {
8      "index": 0,
9      "message": { "role": "assistant", "content": "Community-hosted AI inference." },
10      "finish_reason": "stop"
11    }
12  ]
13}

Routing & priority headers

By default a request enters the normal queue and bills the standard price of whichever live host serves it. Two optional headers let you target a host and skip its line.

Field	Type	Description
X-Pied-Piper-Host	string	Pin the request to a specific host id (from the marketplace).
X-Pied-Piper-Priority	boolean	Use the host's priority lane. Bills `price × multiplier`. Must be paired with `X-Pied-Piper-Host`.

priority request

1curl https://mesh-zeta-eight.vercel.app/v1/chat/completions \
2  -H "Authorization: Bearer $PIEDPIPER_API_KEY" \
3  -H "X-Pied-Piper-Host: 7f3c...host-id" \
4  -H "X-Pied-Piper-Priority: true" \
5  -H "Content-Type: application/json" \
6  -d '{ "model": "llama-3.2-3b-instruct-q4f32_1",
7        "messages": [{ "role": "user", "content": "ping" }] }'

Priority needs a target

Sending X-Pied-Piper-Priority: true without X-Pied-Piper-Host returns a 400 invalid_request_error— Pied Piper can't bill a priority multiplier without knowing whose lane you're jumping.

List models

GET/v1/models

Returns the enabled catalog in OpenAI's { object: "list", data: [...] } shape, so openai.models.list() just works. Each entry is { id, object: "model", created, owned_by: "pied piper" } where id is the model slug. The full list is returned regardless of which models are live right now.

Errors

Errors use OpenAI's envelope — { error: { message, type, code } } — with conventional HTTP status codes, so existing error handling keeps working.

Field	Type	Description
400	invalid_request_error	Malformed body, bad params, or missing required fields.
401	authentication_error	Missing, malformed, unknown, or revoked key.
403	permission_error	Authenticated but not allowed (e.g. insufficient credits).
404	not_found_error	Unknown model, host, or expired rental token.
429	rate_limit_error	Too many requests — back off and retry.
503	service_unavailable_error	No live host could serve the model within the wait window.
502	api_error	Internal error on Pied Piper's side.

401 Unauthorized

1{
2  "error": {
3    "message": "Unknown or revoked key.",
4    "type": "authentication_error",
5    "code": "invalid_api_key"
6  }
7}

Limits

Field	Type	Description
Request body		256 KB total.
Messages		200 per request.
Message length		200,000 characters per message.
Dispatch wait		Up to ~60s for a host to free up or warm a model before `503`.