Developer docs

Quick start

Plenum Cloud exposes an OpenAI-compatible API. Existing OpenAI SDK projects migrate by changing only base_url and the API key.

1. Register and create a key under "API Keys" in the console (plaintext shown once). 2. Point base_url at Plenum. 3. Call as usual.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.plenumcloud.ai/v1",
    api_key="pln-...",
)

stream = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Hello, Plenum"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

API

Authentication

All /v1 requests use Authorization: Bearer <API key>. Keys start with pln-; revocation takes effect immediately.

Streaming

Set stream: true. The gateway automatically injects stream_options.include_usage so the final SSE chunk carries usage — the basis for metering; no manual setup needed.

Metering & usage

Each request is metered and priced across four token classes, reported in the usage object:

The console "Usage" and "Billing" views use the same definitions and drill down by model and key; invoices follow platform metering.

Prefix caching

Cached input tokens cost far less than uncached ones, and the saving is passed through in pricing. Agent workloads (long system prompts, tool definitions, multi-turn history) hit naturally — provided the prefix is byte-stable:

Hit rate is observable per key in the console.

Rate limits & quotas

Each API key has its own per-minute request limit (token bucket with short bursts) and an optional monthly token quota. Exceeding either returns 429 with error.code identifying the cause; clients should retry with exponential backoff. Dedicated-endpoint limits follow the contract.

Error codes

Errors follow the OpenAI shape: { "error": { "code", "message" } }.

4xx errors are not retried; connection failures, 5xx and upstream 429s fail over across candidate upstreams automatically.

Dedicated endpoints

A dedicated endpoint is exclusive inference capacity: your requests route only to the node bound to you, never shared with other customers or subject to shared-pool limits; billed by capacity × time regardless of token usage.

Compute onboarding

Teams with idle GPUs can list clusters for rent. Requirement: the node exposes an OpenAI-compatible streaming chat-completions endpoint (vLLM / SGLang etc.), reachable over the internet or a private link.

Console API

The management API behind the console lives under /admin/v1, authenticated with a session token (Authorization: Bearer <session>), separate from API keys. Useful for automating usage and billing queries: