API

Chat completions

The endpoint almost every request goes to. Same body you already send, plus an optional block for choosing who serves it.

Endpoint

http

POST /v1/chat/completionsAuthorization: Bearer $VACUUM_KEYContent-Type: application/json {  "model": "llama-3.3-70b-instruct",  "messages": [    { "role": "system", "content": "You answer in one paragraph." },    { "role": "user", "content": "Why is inference cheaper on idle consumer GPUs?" }  ],  "max_tokens": 400,  "temperature": 0.7}

Request body

Field	Type	Description
modelrequired	string	A catalogue ID such as `qwen2.5-32b-instruct`, or a full registry ID to pin an exact build. See Models.
messagesrequired	array	Roles `system`, `user` and `assistant`. Content is a string; image parts are rejected until the confidential and multimodal tiers ship.
max_tokens	integer	Output cap, and the number your cost reservation is based on. Defaults to 1024. Set it deliberately — a large value holds more of your balance during the call.
temperature	number	0–2. Defaults to 1.
top_p	number	Nucleus sampling. Defaults to 1.
stop	string \| string[]	Up to four sequences that end the generation.
stream	boolean	Server-sent events instead of one body. See Streaming.
seed	integer	Best-effort. Nodes differ in hardware, so identical seeds are not bit-identical across them.
vacuum	object	Routing controls. Vacuum-specific, and ignored by other providers if you share a config.

Routing controls

By default the router picks the cheapest node that meets the model’s requirements and has a good record. The vacuum block narrows that when you need it to.

json

{  "model": "qwen2.5-32b-instruct",  "messages": [{ "role": "user", "content": "..." }],  "vacuum": {    "min_node_class": "Core",    "max_latency_ms": 800,    "min_reputation": 95,    "pin_node": null  }}

Field	Type	Description
min_node_class	string	`Spark`, `Core`, `Forge` or `Vault`. Raising it usually raises throughput and narrows the pool.
max_latency_ms	integer	Excludes nodes whose observed median exceeds this. Too tight a value returns no_capacity.
min_reputation	number	0–100. Above about 98 you are asking for a small pool; expect queuing at peak.
pin_node	string \| null	Route to one specific node. Useful for reproducing a result, and a good way to get rate-limited by that node.

Every constraint you add shrinks the pool, and a shrunken pool is a slower and more expensive one. Start with none of them and add only what a measurement tells you to.

Response

The body matches the format you already parse. Vacuum adds one object and one header, both carrying the same receipt ID.

Field	Type	Description
vacuum.receipt	string	Receipt ID, also sent as x-vacuum-receipt.
vacuum.node	string	The node that served the request.
vacuum.node_class	string	Its hardware class.
vacuum.epoch	integer	The epoch this receipt is committed under. Its Merkle root reaches Arc when the epoch closes.
vacuum.cost_usdc	string	What was actually debited, as a decimal string.

cost_usdc is a string, not a number. Per-request amounts run to the sixth decimal and a float will round them wrong. Parse it as a decimal or work in µUSDC — the smallest unit of the token, a millionth of a dollar.

Not supported

Tool and function calling. Not in Phase 1. The models in the catalogue can emit JSON on request, but there is no server-side tool loop.
Image and audio input. Phase 4, alongside the confidential tier.
n greater than 1. One request is served by one machine, so parallel samples would mean parallel requests. Send them yourself and you keep a receipt for each.
Logprobs. They would leak the signal the audit layer scores against. See Receipts and proofs.