OpenAI-compatible inference,
billed to your Privateer account

Quickstart

Create an API key in the Privateer app under Settings → API keys, then set it as your OpenAI base URL and key. The key looks like sk-priv-… and is shown only once.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.privateer.pro/v1",
    api_key="sk-priv-…",
)

resp = client.chat.completions.create(
    model="",  # "" = your account's default model; or an id from /v1/models
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.privateer.pro/v1",
  apiKey: process.env.PRIVATEER_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

curl https://api.privateer.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"Hello!"}]}'

Authentication

Every request needs a Privateer API key in the Authorization header:

Authorization: Bearer sk-priv-…

Create, name, and revoke keys in the Privateer app under Settings → API keys. The full key is shown once at creation — we store only a hash, so if you lose it, revoke it and mint a new one. A key inherits its owner's plan, rate limits, and credit balance; revoking it stops every request using it immediately.

Pricing. API usage is pay-as-you-go, drawn from your account credit — across chat, image, video and audio. See the current per-model rate card at privateer.pro/api-pricing.

Keys are managed in the app, not over this API. There is deliberately no /v1 endpoint that mints or lists keys — a key cannot create another key, so a leaked one cannot quietly grow itself a replacement. Minting and revoking happen in a signed-in session, in the app.

Privacy & encryption

In the Privateer app, your content is encrypted on your device or in our cloud, with inference on hardware-attested enclaves. This API is different by nature: you send prompts to our server, which forwards them to the model provider to run inference. That traffic is processed in the clear and is not encrypted.

Endpoints

All paths are relative to https://api.privateer.pro/v1.

POST /v1/chat/completions

Standard OpenAI Chat Completions. Tool calls, multi-part content, and finish_reason pass through unchanged. Common parameters:

A successful response is the provider's standard Chat Completion object, including a usage block that determines billing.

Streaming

Set "stream": true to receive Server-Sent Events. Each event is a chat.completion.chunk; the stream ends with data: [DONE]. The final chunk carries usage.

curl -N https://api.privateer.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"model":"","stream":true,"messages":[{"role":"user","content":"Count to 3"}]}'

With the OpenAI SDKs, pass stream=True (Python) / stream: true (Node) and iterate the returned stream as usual.

Vision (image input)

Image input works on /v1/chat/completions with no extra endpoint — pass OpenAI multi-part content and a vision-capable model:

curl https://api.privateer.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "near/Qwen/Qwen3.5-122B-A10B",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,…"}}
      ]
    }]
  }'

Pass a model whose id supports image input (see Models). Data-URI and remote image_urls are both accepted.

Models

GET /v1/models returns the models available to your account in OpenAI's list shape. Use any returned id as the model field; pass an empty string to use your account default.

curl https://api.privateer.pro/v1/models \
  -H "Authorization: Bearer sk-priv-…"

{
  "object": "list",
  "data": [
    { "id": "near/deepseek-ai/DeepSeek-V4-Flash", "object": "model", "owned_by": "privateer" }
  ]
}

Image generation

OpenAI Images shape. Returns base64 by default (b64_json), or set response_format:"url" for a short-lived signed URL. n is capped at 4. Leave model empty for your account's default image model.

curl https://api.privateer.pro/v1/images/generations \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"an otter surfing, watercolor","n":1}'

{
  "created": 1783437233,
  "data": [ { "b64_json": "/9j/4AAQ…" } ]
}

Video generation

Video generation is asynchronous: submit a job, then poll it. This is a Privateer extension (no OpenAI equivalent). The finished video is returned as a short-lived signed URL.

curl https://api.privateer.pro/v1/videos \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a butterfly landing on a flower","seconds":4}'

# → 202
{ "id": "NzX8ue0…", "object": "video.job", "status": "queued" }

curl https://api.privateer.pro/v1/videos/NzX8ue0… \
  -H "Authorization: Bearer sk-priv-…"

# processing…
{ "id": "NzX8ue0…", "status": "processing" }

# done
{ "id": "NzX8ue0…", "status": "completed",
  "url": "https://…signed…", "expires_at": 1783440833 }

This endpoint is text-to-video: the prompt is the only conditioning it takes. Image conditioning — pinned first/last frames, reference images, continuing or altering an existing clip — is available in the Privateer apps, not on /v1. For image conditioning that is on the API, see 3D model generation below.

Optional submit fields: model, seconds, size, generate_audio, requireZdr. The signed url is short-lived — each poll of a completed job returns a fresh one. Video requires a paid plan (or held pay-as-you-go credit).

3D model generation

Turn reference images into a 3D mesh you can import into a game engine or DCC tool. Like video, this is asynchronous and a Privateer extension: submit a job, then poll it. The finished mesh is returned as a short-lived signed URL.

It is image-to-mesh — there is no text-to-mesh endpoint. Send between one and four views of the same object as base64 (or a data: URI); extra views stop the model inventing the sides it cannot see. Remote image URLs are not accepted.

Several models are available, from different labs, and they do not take the same options — one is configured by output resolution, another by a texture tier, another by a quality preset. So start by listing them: GET /v1/models3d returns every model with its price, its output formats, how many views it uses, and the exact options it accepts. Pass the ones you choose as axes.

curl https://api.privateer.pro/v1/models3d \
  -H "Authorization: Bearer sk-priv-…"

{ "object": "list", "data": [
  { "id": "fal-ai/trellis-2", "object": "model3d", "name": "Trellis 2",
    "formats": ["glb"], "max_views": 1, "price_usd": { "min": 0.35, "max": 0.49 },
    "axes": [
      { "name": "resolution", "kind": "enum", "priced": true,
        "default": "1024", "values": ["512", "1024", "1536"] },
      { "name": "faceCount", "kind": "int", "priced": false,
        "min": 5000, "max": 2000000 } ],
    "conflicts": [] }, … ] }

curl https://api.privateer.pro/v1/models3d \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"image":"iVBORw0KGgo…","model":"fal-ai/trellis-2",
       "axes":{"resolution":"1536","faceCount":250000}}'

# → 202
{ "id": "01a0051b…", "object": "model3d.job", "status": "queued",
  "format": "glb", "estimated_cost_usd": 0.49 }

curl https://api.privateer.pro/v1/models3d/01a0051b… \
  -H "Authorization: Bearer sk-priv-…"

# processing… (typically 60–90 seconds)
{ "id": "01a0051b…", "status": "processing" }

# done
{ "id": "01a0051b…", "status": "completed", "format": "glb",
  "url": "https://…signed…", "expires_at": 1783440833 }

The named fields above are the older, Hunyuan-shaped spelling and still work; axes is the general one and wins where both are sent. It is the only way to reach the options on the other models.

Cost depends on which model you pick and which options you set — the spread across the catalog is more than tenfold, and an option that is a surcharge on one model is free on another, which is why the price lives in the list response rather than here. The submit response reports estimated_cost_usd for your exact request before you commit to polling; that is the figure that gets charged. 3D generation requires a paid plan (or held pay-as-you-go credit).

Audio (speech-to-text, text-to-speech & sound effects)

Transcription (STT) — POST /v1/audio/transcriptions

OpenAI Whisper shape: multipart upload with a file field (or JSON { "audioBase64", "format" }). Returns { "text": … }.

curl https://api.privateer.pro/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-priv-…" \
  -F file=@speech.mp3 \
  -F model=openai/whisper-1 \
  -F requireZdr=false

Speech (TTS) — POST /v1/audio/speech

Returns raw audio bytes. The default voice model returns audio/wav; request response_format:"mp3" only with an mp3-capable model.

curl https://api.privateer.pro/v1/audio/speech \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"input":"Hello from Privateer.","voice":"Zephyr"}' \
  --output speech.wav

Sound effects — POST /v1/audio/sfx

One short sound from a text description. Returns raw audio/mpeg bytes, plus an X-Privateer-Duration-Seconds header giving the length actually rendered.

input is required (max 500 characters). duration is in seconds and is clamped to 1–30, defaulting to 5 — a value outside that range is corrected, not rejected.

curl https://api.privateer.pro/v1/audio/sfx \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"input":"a heavy wooden door slamming shut","duration":3}' \
  --output door.mp3

Search & fetch

The piece an OpenAI-compatible base URL can't supply on its own: live web results to ground an answer with. Same base URL, same sk-priv-… key, same bill — no second vendor and no second API key to hold.

Search — POST /v1/search

query is required. count is clamped to 1–10 (default 5), and freshness takes pd, pw, pm or py — past day, week, month or year — with anything else ignored rather than rejected.

curl https://api.privateer.pro/v1/search \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"query":"webgpu browser support","count":5,"freshness":"pm"}'

Returns { "query", "results": [{ "title", "url", "description", "age", "image" }] }. age and image are present only when the index has them. Add "include_media": true for images and videos arrays alongside the results — they ride along on the same upstream response, so they cost nothing extra and are withheld by default only to keep the payload small.

Fetch — POST /v1/fetch

Reads pages and returns their extracted text. Pass one url, or a urls array of up to 3 — anything beyond that comes back marked failed rather than being silently dropped. http/https only; private and internal addresses are refused.

curl https://api.privateer.pro/v1/fetch \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/changelog"}'

Returns { "anyFailed", "results": [{ "ok", "url", "title", "text" }] }, with error in place of text on a page that couldn't be read. Text is truncated at 20,000 characters per page. A URL that fails is reported per result — the request itself still succeeds.

Agent Client Protocol

Everything above is the hosted inference API. This section is different: it's about the Privateer agent — the one that runs on your own machine — and how other tools can drive it.

Privateer speaks the Agent Client Protocol (ACP), the same interface Zed and other editors use to talk to coding agents. A host launches privateer acp and speaks newline-delimited JSON-RPC over stdio; the host owns the transport and the interface, Privateer owns the agent.

privateer acp

The point of running it this way is that the moat comes with it. The host renders approvals, it does not grant them:

• The permission gate still decides. Every action is classified locally and gated actions are sent to the host as session/request_permission. A cancelled dialog, an unparseable answer, or a host that can't be reached all resolve to deny.
• The tool ceiling is yours, not the host's. Set acp.tools in ~/.privateer/config.json. A host cannot widen it.
• Destructive actions can never become standing permission. Dangerous shell and guarded files are never offered an "allow always" option, so they re-confirm every time.
• Your models, your account. The agent offers its own model list over the protocol, including the confidential TEE models, and runs on your subscription.

Configure it under an acp block in ~/.privateer/config.json. The default ceiling is read-only:

{
  "acp": {
    "tools": ["read", "grep", "find", "ls"],
    "posture": "approve"
  }
}

posture is readonly, approve (default — each risky action asks), or auto. The working directory comes from the host per session, and access outside it is refused rather than prompted.

Add Privateer to Buzz

Buzz is Block's self-hostable workspace where people and agents share the same channels. Because Buzz drives agents over ACP, Privateer drops in as a custom harness and you can message it like a teammate.

In Buzz Desktop, add a custom harness with:

Use absolute paths for both. Buzz is a desktop app and inherits a minimal PATH, so a version-managed node (nvm, asdf) usually isn't on it. The path to privateer-acp.mjs is a separate argument, not part of the command.

Then create an agent that uses the harness. Two settings are worth changing:

Buzz holds the agent's Nostr identity, so its display name and avatar are set on the Buzz side, not by Privateer.

Connectors (MCP)

Privateer is an MCP client. Point it at a Model Context Protocol server and that server's tools become first-class agent tools — available to the CLI, the desktop app, the always-on harbor's unattended routine runs, and to any ACP host driving the agent. Two kinds:

Configuration

Connectors live in two files under the agent's home. The first is the source of truth; the second is generated from it and is the standard shape the MCP adapter reads — edit the source, never the projection.

~/.privateer/agent/mcp-desktop.json   # source of truth — every connector, each with `enabled`
~/.privateer/agent/mcp.json           # projection: enabled connectors only

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "…" }
    },
    "linear": {
      "url": "https://mcp.linear.app/sse",
      "auth": "oauth"
    }
  },
  "settings": { "toolPrefix": "server" }
}

Both files sit in the shared ~/.privateer home, so one machine has one coherent connector config whichever surface edited it — the terminal, the desktop app over loopback IPC, or the phone over the relay.

Adding one

In the terminal, /connect opens a picker over a curated catalog of 22 connectors (GitHub, Slack, Notion, Linear, Jira & Confluence, Sentry, Stripe, Asana, Supabase, Figma, Gmail, Google Drive, PostgreSQL, Playwright, Filesystem, …) plus a Custom connector entry that takes any stdio command line or any https:// URL. It reloads the adapter in place, so new tools are live in the session you're already in. /mcp is the adapter's own status view — what actually connected. The Privateer app and the desktop app have the same editor.

Tools and the permission gate

By default the adapter exposes MCP through a single proxy tool named mcp: one grant covers every enabled server. When a scheduled routine carries a per-connector allow-list, Privateer instead scopes that run to exactly the selected servers and tools, each registered under its own <server>_<tool> name — so an unattended task can hold GitHub's create_issue without holding all of MCP.

Either way, every MCP tool is classified and gated exactly like a built-in. Under ACP that means an MCP tool call surfaces as a session/request_permission to the host, and your acp.tools ceiling still applies — a tool is not trusted because you configured the server it came from.

Credentials

Editing connectors from the phone or web app is the one place that's different, because the relay in between is untrusted: secrets are write-only in both directions. A listing returns env and header names and which of them are set, never a value; a value you type on the phone is sealed to that terminal's pinned key before it leaves the device, and the whole save is signed by your account — so the relay can neither read a credential nor forge a connector.

Hosted (Harbor) agents are OAuth-only by design: no stdio child processes and no stored tokens, because a hosted tenant's home is tmpfs and a durable secret would have to rest somewhere we could read. During the current preview they carry no connectors at all.

Full setup and troubleshooting live in the CLI guide.

Billing & limits

Usage is billed to your Privateer credit balance at your plan's rate, metered by the usage token counts on each completion. Top up and see your balance in the app. Requests are subject to your plan's per-minute rate limit, daily message cap, and a small minimum-balance check — the same limits that govern the app.

Retry 429s with backoff, honouring retryAfter when present. A CONCURRENCY_LIMIT means slow down your fan-out, not your rate — waiting for an in-flight request to settle is what clears it.

Errors

There are two error shapes, and it matters which one you get. Errors raised by an endpoint itself — bad input, a provider failure, a blocked model — use OpenAI's envelope, so an OpenAI SDK parses them normally. Errors raised by the gates that run before the endpoint (rate limit, credit check, plan caps, concurrency) return a flat body instead. An SDK that only reads error.message will see nothing on those; read the top-level code as well.

{ "error": { "message": "…", "type": "invalid_request_error", "code": "INVALID_REQUEST" } }

{ "code": "RATE_LIMITED", "message": "…", "retryAfter": 37 }

Provider errors are forwarded rather than reinterpreted, so an unfamiliar code in the envelope generally came from upstream.