Antimatter

POST/v1/chat/completionsAPI keyNo key

The single dispatch path: rate limit, monthly spend cap, preset expansion, alias resolution, max_tokens clamp, autopilot resolution, key policy, credits, prompt cache, then the candidate walk. Unknown fields are passed through to the upstream verbatim. With no key and x402 on, a 402 names the price; see GET /api/x402. On a deployment with $ANTI holder tiers, a model still in its holders' window (holders_only_until on GET /v1/models) is refused to a key whose minting account holds no tier with 403 holder_only, and autopilot never routes such a key to one.

Request body

application/json, required

Request body fields
Field	Type	What it is
modelrequired	string	A catalog id from GET /v1/models, one of your aliases, preset/<name>, or an autopilot policy id (antimatter/auto, antimatter/auto:cheap, antimatter/auto:fast, antimatter/auto:code, antimatter/auto:extract, antimatter/auto:reason, antimatter/auto:long, antimatter/auto:vision, antimatter/auto:tools, antimatter/auto:json). At most 200 characters.
models	array of string	Ordered fallback list tried in turn when a candidate fails with a retryable error (429 or 5xx). At most 4 entries, so at most 5 candidates including model. The x-antimatter-model response header names the id that actually answered.
messagesrequired	array of object
messages[].rolerequired	string	One of "system", "user", "assistant", "tool".
messages[].content	string or array of object or null
messages[].tool_call_id	string	At most 300 characters.
messages[].name	string	At most 300 characters.
messages[].tool_calls	array of object
stream	boolean	Server-sent events in the OpenAI chunk format, terminated by data: [DONE].
max_tokens	integer	Clamped rather than refused: to the model's own published max output where the catalog has it (max_output_tokens on its GET /v1/models entry), and to the deployment ceiling (ANTIMATTER_MAX_OUTPUT_TOKENS, 131072 by default). A clamp is announced as max_tokens=<sent> in x-antimatter-adjusted. Absent means 4096 (ANTIMATTER_DEFAULT_OUTPUT_TOKENS), or the model's max output if that is lower. At most 9007199254740991.
temperature	number	From 0 to 2.
top_p	number	From 0 to 1.
stop	string or array of string
tools	array of object	Passed through to the upstream verbatim.
tool_choice	string or object
parallel_tool_calls	boolean
response_format	object	Passed through to the upstream verbatim.
seed	integer	From -9007199254740991 to 9007199254740991.
frequency_penalty	number	From -2 to 2.
presence_penalty	number	From -2 to 2.
prompt	object	A prompt kept here: its version's messages come before these, and a request that names no model takes the version's. With no version or label, the production label when it is set, else the newest version.
prompt.idrequired	string
prompt.version	integer or string	A version number, or a label such as production.
prompt.label	string
prompt.variables	object	A value for every {{variable}} the version names, and no others.

Example

{
  "model": "antimatter/auto",
  "messages": [
    {
      "role": "user",
      "content": "Say hello in five words."
    }
  ]
}

Answer 200

The completion, or an SSE stream of chunks when stream is true. Carries x-antimatter-upstream, x-antimatter-model, and, where they apply, x-antimatter-byok, the cache family, and the routing explanation.

Headers: x-antimatter-upstream, x-antimatter-request-id, x-request-id, x-antimatter-cost-micros, x-antimatter-cost-breakdown, x-antimatter-adjusted, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, x-antimatter-model, x-antimatter-byok, x-antimatter-cache, x-antimatter-cache-prefix, x-antimatter-cache-similarity, x-antimatter-cache-cost-micros, x-antimatter-cache-note, x-antimatter-cache-control, x-antimatter-auto-cache, x-antimatter-hedge, x-antimatter-coalesced, x-antimatter-route, x-antimatter-route-warning, x-antimatter-fallback, x-antimatter-json, x-antimatter-compress, x-antimatter-pii-redacted, x-antimatter-pii-kinds, x-antimatter-prompt-version, x-antimatter-memory, x-antimatter-overhead-ms, x-antimatter-stream-id

Fields of the 200 answer
Field	Type	What it is
id	string
object	"chat.completion"
created	integer
model	string
choices	array of object
choices[].index	integer
choices[].message	object
choices[].message.role	string
choices[].message.content	string or null
choices[].finish_reason	string or null
usage	Usage
usage.prompt_tokens	integer
usage.completion_tokens	integer
usage.total_tokens	integer
usage.cost	number	What this answer was billed, in dollars: the same figure as x-antimatter-cost-micros.
usage.cost_details	CostDetails	usage.cost_details: what usage.cost is made of, in dollars, summing to it exactly. The same figures as the x-antimatter-cost-breakdown header. Never the upstream's own reported charge.
usage.cost_details.input	number	Prompt tokens at the upstream's input rate.
usage.cost_details.cached_input	number	Prompt tokens the vendor served from its cache, at its cache read rate.
usage.cost_details.cache_write	number	Prompt tokens written into the vendor's cache, at its cache write rate.
usage.cost_details.output	number	Answer tokens other than reasoning.
usage.cost_details.reasoning	number	Reasoning tokens, inside completion_tokens, at the output rate.
usage.cost_details.tools	number	A paid tool or search beside the tokens.
usage.cost_details.margin	number	The operator's stated markup on the parts above, less any discount.
usage.cost_details.other	number	What no card explains: a replayed cached answer, or an upstream charge above its published card, passed on at cost plus the markup.

Errors

400OpenAI shaped error.
401OpenAI shaped error.
402A funded account whose balance reached zero. An account that has never deposited is never gated this way.
403The key's policy refused the request: policy_violation when no candidate is on the allowlist, a model is on the blocklist, or the wire is not one the key may use; policy_exceeded when a named limit is spent; request_cost_exceeded when the request's worst case cost is over the key's per request ceiling.
404OpenAI shaped error.
422Strict JSON (x-antimatter-json): every answer failed the JSON check. error.type json_invalid, error.attempts, and error.content with the last answer; every attempt was billed, in x-antimatter-cost-micros.
429Rate limited, or a spent budget or spend cap. The type distinguishes rate_limit_error, policy_exceeded, and spend_cap_exceeded.
499The client closed the connection before the response finished.
502OpenAI shaped error.
503OpenAI shaped error.
504The upstream did not answer within the gateway's timeout (upstream_timeout).

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.

Request headers it reads (14)

Request headers
Field	Type	What it is
x-antimatter-session	string	A free form label that groups requests in the log. Printable ASCII, trimmed to 120 characters. At most 120 characters.
x-antimatter-cache	string	Send on to opt into the exact match and prefix cache layers, or semantic to add the similarity layer on a key that enabled it. Non streaming only, never for a request served on your own provider key, and always scoped to your account. The response echoes x-antimatter-cache: hit, semantic, or miss. A hit costs nothing and spends no credits. One of "on", "semantic", "off".
x-antimatter-route	string	A JSON object steering one autopilot decision. Every field is optional: policy (balanced, cheap, fast, quality), weights (price, latency, quality), max_price_per_1m, min_context, modality, require_tools, require_json. It shapes the routing of an antimatter/auto id only; a request that named a model is dispatched to that model and the directive is reported back in x-antimatter-route-warning as ignored rather than applied quietly. Anything unreadable in the object is reported the same way. At most 2000 characters.
x-antimatter-cache-control	string	Send auto to let the gateway place one provider side cache_control breakpoint at the boundary of a thread prefix a chain hash has proved unchanged. It does nothing when you placed your own markers, when the thread is not a verified continuation, or on a model whose wire does not read cache_control. The response says which in x-antimatter-cache-control. One of "auto".
x-antimatter-auto-cache	string	Automatic prompt caching for this request, over the key's autoCache policy and the deployment's default. On an Anthropic world the gateway marks a prompt start this account sent within five minutes (the system prompt and tools, or the conversation so far) so the vendor serves it from its cache; Gemini, OpenAI, DeepSeek and Grok cache by themselves. Cached tokens are billed at the world's cache read rate and written ones at its write rate; the hold stays the uncached worst case plus the write premium. One of "on", "off".
x-antimatter-hedge	string	<ms>; max=<micros>, or off. When the first source has sent no byte in that many milliseconds (50 to 60000), the same request goes to a second source of the same world at the same card and the first answer wins; the other is cancelled and billed its prompt bound, which must fit under max or nothing is hedged. Never on your own provider key or under strict JSON. Over the key's hedgeMs and hedgeMaxMicros.
x-antimatter-resumable	string	Send 1 on a streaming request made with a key to make the stream resumable. The answer carries x-antimatter-stream-id and numbers every SSE event with an id: line. If the connection drops, the generation carries on to its end and is billed in full, once, exactly as if you had stayed; pick it up at GET /v1/streams/{id}. The output is kept for ANTIMATTER_RESUME_TTL_S (600 s) after its last write, up to ANTIMATTER_RESUME_MAX_BYTES (4 MiB) of frames. Ignored on a request that does not stream, and on an x402 paid request, which has no key to resume with. One of "1".
x-antimatter-fallback	string	Send comparable to fall back, when the requested world and its models chain fail with a retriable error or every provider of it has an open breaker, to the nearest world priced at or below it on both sides with the capabilities and context this request needs, inside the key's allow and block lists. A request on your own provider key only falls back to a world that key serves. off turns off the key's own setting for this request. The answer names what happened in x-antimatter-fallback. One of "comparable", "off".
x-antimatter-json	string	Send strict on a request whose response_format is json_object or json_schema to have the answer checked before it is handed over: it must parse, and for json_schema match the schema (format annotations are not checked). An answer that fails is asked for once more on the same world with a short repair note, then from the comparable fallback when one is set. Every attempt is billed as a live call and the hold covers two. A final failure is a 422 json_invalid carrying the last answer as error.content. On a stream the answer is asked for whole and checked first, so the first byte waits for the check; the checked answer then streams as chunks. off turns off the key's strictJson policy for this request. One of "strict", "off".
x-antimatter-compress	string	Prompt compression, off unless asked for. safe: a document or tool result repeated later in the thread is sent once and each later copy becomes a short reference to the first; trailing spaces and blank line runs in long pasted blocks are tidied outside code fences; a long system prompt goes first in the system block; and on a world that reads cache_control, breakpoints mark the end of the stable prefix. aggressive: safe, and the turns before the last few are replaced by a summary from the cheapest paid model the key may use (or model=<id>; keep=<n> moves the cut), a request of its own, metered and billed. A short thread is not summarized, nor the last user turn or a tool call still waiting on its result. off turns off the key's compress policy for this request.
x-antimatter-memory	string	Long term memory, where the operator has it on: a memory space id, or default for the key's own. The memories nearest the last user turn, of the request's end user (user on chat completions, metadata.user_id on /v1/messages, user or else safety_identifier on /v1/responses), go in front of the model in the wire's own system field: one system message after the caller's own on chat completions, a paragraph at the end of system on /v1/messages, a paragraph at the end of instructions on /v1/responses (the answer still echoes the instructions as sent). The recall is one embeddings request billed as the key, which needs the embeddings scope.
x-antimatter-memory-write	string	1: after the answer, the conversation and the answer's text are queued for extraction into the space named by x-antimatter-memory (or the default), read and billed as the key like POST /v1/memories. On chat completions, /v1/messages and /v1/responses; a stream is read as it passes. One of "1".
x-antimatter-prompt	string	A prompt kept here, by header instead of the body's prompt field: pmpt_..., pmpt_...@3 for a version, pmpt_...@staging for a label. With neither, the production label when it is set, else the newest version.
x-antimatter-prompt-variables	string	The prompt's values as a JSON object, beside x-antimatter-prompt.

Try it

The same call with curl

curl -X POST https://useantimatter.com/v1/chat/completions \
  -H "Authorization: Bearer $ANTIMATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"antimatter/auto","messages":[{"role":"user","content":"Say hello in five words."}]}'