Build with Pied Piper

SDK

@piedpiperrh/sdk is a small, typed, zero-dependency TypeScript client for the Pied Piper API. It runs anywhere fetch exists — Node ≥ 18, Bun, Deno, and the browser — and ships both ESM and CJS builds.

Install

shell

1npm install @piedpiperrh/sdk

Use it

Construct a PiedPiper client with a key from Settings → API keys and call chat.completions.create. No base URL needed — it points at Pied Piper out of the box. Model slugs come from client.models.list() or the catalog.

typescript

1import PiedPiper from "@piedpiperrh/sdk";
2
3const client = new PiedPiper({
4  apiKey: process.env.PIEDPIPER_API_KEY!,
5});
6
7const r = await client.chat.completions.create({
8  model: "llama-3.2-3b-instruct-q4f16_1",
9  messages: [{ role: "user", content: "Hello!" }],
10});
11
12console.log(r.choices[0].message.content);

Streaming

Pass stream: true and the same call returns an async iterable of OpenAI-style chunks.

typescript

1const stream = await client.chat.completions.create({
2  model: "llama-3.2-3b-instruct-q4f16_1",
3  messages: [{ role: "user", content: "Write a haiku about GPUs." }],
4  stream: true,
5});
6
7for await (const chunk of stream) {
8  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
9}

Routing options

Host pinning, priority, and capacity waits are typed options on the second argument — the SDK translates them to the X-Pied-Piper-* routing headers described in Marketplace & priority.

typescript

1const r = await client.chat.completions.create(
2  {
3    model: "llama-3.2-3b-instruct-q4f16_1",
4    messages: [{ role: "user", content: "ping" }],
5  },
6  {
7    host: "7f3c...provider-session-id", // pin to one host
8    priority: true,                     // skip the queue (costs more)
9    waitSeconds: 30,                    // wait for capacity instead of failing fast
10  },
11);

Errors

Failed requests throw PiedPiperError with the HTTP statusand the API's error code (insufficient_credits, no_capacity, rate_limited, …).

typescript

1import { PiedPiperError } from "@piedpiperrh/sdk";
2
3try {
4  await client.chat.completions.create(params);
5} catch (err) {
6  if (err instanceof PiedPiperError && err.code === "no_capacity") {
7    // retry with { waitSeconds: 60 }
8  }
9}

Or just use OpenAI

The SDK is optional. Point any OpenAI-compatible client at the Pied Piper base URL and everything in the API reference applies unchanged.

typescript

1import OpenAI from "openai";
2
3// The wire format is OpenAI-compatible — any OpenAI client works too.
4const client = new OpenAI({
5  apiKey: process.env.PIEDPIPER_API_KEY,
6  baseURL: "https://mesh-zeta-eight.vercel.app/v1",
7});