Docs spread across products
A dozen endpoints for a dozen features means a dozen things to get wrong.
API reference
One endpoint, fully documented
Everything you need to call POST /api/ainf/inference with confidence: authentication, request fields, the response object and the errors you should handle.
One endpoint
POST /api/ainf/inference
JSON in, JSON out
no special client required
Clear errors
a status code and a message
The problem
What is slowing you down today
Errors without meaning
A bare 500 tells you nothing about whether to retry.
Hidden response fields
Usage and price should come back with the answer, not from a separate report.
Capabilities
Everything you need, nothing you don't
Authentication
Header Authorization: Bearer <API key>. The account is taken from the verified credential, never from the body. Missing or invalid credentials return 401.
Request body
prompt (string, required, up to 100,000 characters); model_id (string, optional); capability (string, optional, defaults to chat); temperature (number, optional, 0 to 2, default 0.7); max_tokens (integer, optional, 1 to 8192, default 1024).
Idempotency-Key header
Optional. A unique string per logical operation, namespaced to your account. Usage for a given key is metered once. An idempotency_key body field is accepted as a fallback.
Response
200 with {"ok": true, "result": {id, response, model_id, model_name, input_tokens, output_tokens, total_tokens, latency_ms, cache_hit, price_micros, status}}. status is success or cached.
Errors
Errors return {"error": "message"}. 400 missing or too-long prompt; 401 not signed in; 403 account suspended; 404 named model not found; 409 model disabled or no model for the capability; 429 rate limit reached; 502 the request could not be completed after fail-over; 503 inference temporarily unavailable.
Supporting endpoints
GET /api/ainf/models lists enabled models with capabilities and per-1K-token prices. GET /api/ainf/requests returns your paginated request history.
Use cases
What teams run on it
01
Routed request
{"prompt": "Summarise this ticket...", "capability": "chat"} lets the router pick the lowest-priced enabled chat model.
02
Pinned request
{"prompt": "...", "model_id": "<catalog id>"} uses that model only, with no substitution.
03
Deterministic-leaning output
Set temperature to 0 for extraction and classification tasks.
04
Bounded output
Set max_tokens to cap the length, and the cost, of a response.
How it works
From sign-up to production
- 1
Authenticate
Send your bearer key on every request.
- 2
Send the body
At minimum a prompt; add capability or model_id, temperature and max_tokens as needed.
- 3
Handle the status
Read result on 200. On 429, 502 or 503, back off and retry with the same Idempotency-Key.
Control
Built so you stay in charge
Keys you control
API keys are shown once at creation and stored only as a hash. Revoke any key instantly from Settings.
Spend you can see
Every request carries its own receipt: tokens in, tokens out, latency and price. Nothing is billed that you cannot trace.
Limits you set
Per-account rate limits and a free monthly allowance keep experiments safe before they become production.
Data you decide on
You choose exactly what you send. Repeat prompts can be served from your cache, and cache hits are never billed.
For developers
One endpoint. Every model.
Send a prompt and a capability, or name a model. One bearer key, one small JSON body, and a full receipt on every response.
curl https://YOUR-DOMAIN/api/ainf/inference \
-H "Authorization: Bearer $AI_INFERENCE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"prompt":"Summarise this ticket in one line","capability":"chat"}'Questions, answered
Which errors are safe to retry?
429, 502 and 503 are transient. Retry with backoff and reuse the same Idempotency-Key so usage is metered once. 400, 401, 403, 404 and 409 need a change before retrying.
Does fail-over change the response shape?
No. model_id and model_name tell you which model served the request; everything else is identical.
What units are prices in?
price_micros is millionths of a US dollar. Catalog prices are per 1,000 input and output tokens in the same unit.
Is there a response size limit?
max_tokens caps the output, up to 8192 tokens per request.
Everything you need, one endpoint
Create a key and start calling POST /api/ainf/inference today.