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, audio and 3D. Per-model rates for the whole catalogue are at privateer.pro/models; how each kind is metered is at what media costs, and how billing works 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" }
  ]
}

What media costs

Chat is billed per token. Everything else is billed per unit of output, and the unit is the provider's own — we don't convert, because converting would mean inventing the resolution, duration or token count your request actually decides.

Live per-model rates for all of them — image, video, music, sound effects, voices and 3D, each with its id and its unit — are on privateer.pro/models, quoted at the same developer-API rate this key bills at.

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 and sprite sheets 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).

Sprite sheets (Godot)

Turn frames into a packed sprite sheet with a Godot 4 SpriteFrames resource beside it, or start a facing further back than that — a picture and a sentence — and let Privateer render the motion first. Either way the response is one archive: the sheet, the individual frames, a .tres you can drop straight onto an AnimatedSprite2D, and a README saying where to put them.

Two endpoints, because they need very different things from the deployment:

• POST /v1/sprites packs frames you already hold. It calls no model, so it is synchronous and not billed — there is no daily cap and no balance check on it.
• POST /v1/sprites/generate renders the frames first, from one image and a description of the motion. It is asynchronous and billed, one video generation per facing that isn't mirrored.

Start at GET /v1/sprites/models. It is the only way to tell “this deployment can't” from “my request was wrong”: generation needs a video decoder on the server, and where there isn't one, generate.available is false and generation refuses with 503 SPRITE_GENERATION_UNAVAILABLE before anything is billed. Packing is unaffected and works everywhere. Like the 3D catalog, this endpoint is behind no plan or balance gate.

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

{ "object": "list",
  "pack": { "available": true, "input": "PNG frames, base64" },
  "generate": { "available": true, "decoder": "ffmpeg 7.1" },
  "direction_sets": [
    { "id": "one",   "directions": ["default"], "billed": 1, "mirrored": 0 },
    { "id": "four",  "directions": ["down", "right", "up", "left"], "billed": 3, "mirrored": 1 },
    { "id": "eight", "directions": ["down", "down_right", …], "billed": 5, "mirrored": 3 } ],
  "limits": { "frames": { "min": 2, "max": 24 },
              "frame_size": { "min": 8, "max": 512 },
              "max_facings": 8, "max_frame_bytes": 8388608,
              "max_total_input_bytes": 50331648 },
  "output": { "godot": "4.x", "resource": "SpriteFrames", "container": "application/zip" } }

Packing frames you already have — POST /v1/sprites

Send base64 PNGs. One facing is a flat frames array; several are facings, each with its own direction. Every generated facing must carry the same number of frames — the sheet is a grid, and a short row would leave dead cells the resource still points at.

curl https://api.privateer.pro/v1/sprites \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"name":"knight","action":"walk","directions":"four","fps":12,
       "frame_size":64,
       "facings":[{"direction":"down","frames":["iVBORw0…","iVBORw0…"]},
                  {"direction":"right","frames":["iVBORw0…","iVBORw0…"]},
                  {"direction":"up","frames":["iVBORw0…","iVBORw0…"]},
                  {"direction":"left","mirror_of":"right"}]}'

A facing with mirror_of costs nothing and sends no frames — it is the named facing flipped horizontally, which is how left comes free from right. It must name a facing that is in the same request.

# → 200
{ "id": "sprite_9f2c…", "object": "sprite", "status": "completed",
  "url": "https://…signed…", "expires_at": 1783440833, "bytes": 148213,
  "sheet": { "width": 512, "height": 256, "columns": 8, "rows": 4,
              "frame_width": 64, "frame_height": 64 },
  "animations": [ { "name": "walk_down", "direction": "down", "origin": "generated" },
                   { "name": "walk_left", "direction": "left", "origin": "mirrored" }, … ],
  "fps": 12, "loop": true, "res_path": "res://sprites/knight/",
  "spriteframes_tres": "[gd_resource type=\"SpriteFrames\" …",
  "key_residue": 0.0031 }

The archive at url holds <name>_sheet.png, the .tres, a README, and (unless you turned them off) frames/. The resource is also returned inline as spriteframes_tres: it is a few kilobytes of text, and a build step very often wants to read or rewrite the res:// path without unzipping anything.

Generating the frames — POST /v1/sprites/generate

One image and one sentence. Privateer turns your picture to face each direction, renders a short looping clip per facing against a flat backdrop, samples the frames out of it, and packs them exactly as above. Submit, then poll GET /v1/sprites/{id}.

It is image-to-video and refuses without an image rather than quietly falling back to text: a text-rendered clip of “a knight walking” is a different knight every facing, and the turned facings are edits of the picture you supplied — there is nothing to turn without one.

curl https://api.privateer.pro/v1/sprites/generate \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"image":"iVBORw0KGgo…","prompt":"walking, steady gait, looping",
       "name":"knight","action":"walk","directions":"eight",
       "frames":8,"frame_size":64,"fps":12}'

# → 202
{ "id": "sprite_9f2c…", "object": "sprite.job", "status": "queued",
  "billed_facings": 5, "mirrored_facings": 3, "animations": 8 }

# poll
curl https://api.privateer.pro/v1/sprites/sprite_9f2c… \
  -H "Authorization: Bearer sk-priv-…"

{ "id": "sprite_9f2c…", "status": "processing",
  "facings_ready": 2, "facings_total": 5 }

# done — the same body POST /v1/sprites returns, plus object: "sprite.job"

Mirroring is the cost story, and it is said at submit. billed_facings is what you pay for; animations is what you get. An eight-way set costs five video generations, not eight, because left, up_left and down_left are their right-hand counterparts flipped — and the flip happens after keying, so the alpha is byte-identical.

Everything in the packing table above applies here too, plus prompt (required — describe the motion), image (required, base64 or a data: URI), model (a video model id), and image_model (the model that draws the turned facings). Nothing packs until every billed facing has landed: the union bounding box that keeps the character registered is computed across all of them. A facing that fails is dropped and the rest still make a sheet. Billing is reserved per clip at submit and settled on completion; a failed clip releases its hold, and an underfunded fan-out releases everything it had reserved rather than holding your balance against clips that can never be packed.

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

Four endpoints, each taking an optional model. There is no /v1/audio/models to list from: the voices, the sound-effect generators, the music models and the transcription models each come from a different catalogue, and all of them — ids, prices and the unit each is metered in — are published on privateer.pro/models. Omit model and your account's default is used.

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. input is capped at 8,000 characters — longer text is truncated rather than rejected, and you are billed for what we send.

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

Music — POST /v1/audio/music

A full track — sung or instrumental — from a text brief. Returns raw audio bytes, with the model that rendered it in X-Privateer-Model.

input is required (max 2,000 characters). duration is in seconds and is clamped to what the chosen model will render; several models treat it as a hint rather than a contract, which is why the response carries both X-Privateer-Duration-Seconds (what came back) and X-Privateer-Requested-Seconds (what you asked for) instead of relabelling one as the other. Some models are fixed-length and report neither.

curl https://api.privateer.pro/v1/audio/music \
  -H "Authorization: Bearer sk-priv-…" \
  -H "Content-Type: application/json" \
  -d '{"input":"slow dub techno, deep sub bass, tape hiss","duration":60}' \
  --output track.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 — chat metered by the usage token counts on each completion, media metered per unit of output (see what media costs). 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.