QUICK START

Connect in minutes.

Create a key, add credit through your administrator, and send your first request.

Your API endpoint

https://xknwn.io/v1

Use an Xknwn key in your application. Never use your Hiflow management token in client code.

Send a chat request

Choose an available model from Models. This example sets a $0.10 maximum reservation and a short response.

curl https://xknwn.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_XKNWN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-request-001" \
  -H "X-Xknwn-Budget-USD: 0.10" \
  -d '{"model":"gpt-5.4-nano","messages":[{"role":"user","content":"Say hello."}],"max_tokens":32}'

Supported endpoints

GET /v1/models lists the models your key can use. JSON requests are supported at POST /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations and Gemini /v1beta/models/MODEL:generateContent or :streamGenerateContent. Availability depends on the model and its upstream route. Chat, Responses and Messages support streaming.

Credit & limits

Top-ups are manual. Ask your administrator to add credit, then create an API key in your workspace. Each request reserves up to the model limit, your remaining wallet balance, your key allowance, or your optional budget header, whichever is lowest. At least $0.01 is required. Text output defaults to 1,024 tokens and is capped at 8,192 tokens. Up to four requests can be unsettled per account.

Final billing is the provider’s recorded cost plus the model’s saved markup, rounded up to the nearest $0.000001. A $1.00 provider charge with 10% markup costs $1.10. A budget can cause the provider to reject an expensive request; it does not guarantee a particular output length.

Safe retries

Send a unique Idempotency-Key per intended request. Reusing it returns 409 and never sends another model request. Responses are not stored for replay. Save the X-Xknwn-Request-Id header and check Usage if a connection fails. Pending billing retains its hold; never automatically resend an uncertain request with a new reference.

Current boundaries

JSON bodies up to 2 MB and one output per request are supported. Asynchronous video, background jobs, stored response chains, file uploads, multipart audio/image editing and realtime WebSockets are not enabled. Keep API keys on your server; do not publish them in a website or mobile app.