Chat Completions API

Use POST /v1/chat/completions for OpenAI-compatible text generation through Xenodia.

Endpoint

POST https://api.xenodia.xyz/v1/chat/completions

Authentication

Authorization: Bearer YOUR_LONG_TERM_KEY

Minimal request

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Reply with OK only."
    }
  ]
}

cURL

curl -X POST "https://api.xenodia.xyz/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XENODIA_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "messages": [
      { "role": "system", "content": "You are a precise test assistant." },
      { "role": "user", "content": "Reply with OK only." }
    ],
    "temperature": 0
  }'

Success response

{
  "id": "chatcmpl-xxx",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "OK"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 1,
    "total_tokens": 19
  }
}

Usage and billing

usage.prompt_tokens and usage.completion_tokens report Xenodia billable token counts. The applicable token multiplier has already been applied, with each count rounded separately. usage.total_tokens is the sum of these two counts. Do not apply the multiplier again.

For example, 100 input tokens and 200 output tokens with a 1.85 multiplier are returned as 185 input tokens, 370 output tokens and 555 total tokens. These are the quantities recorded for billing.

For stream: true, read the last non-null usage before data: [DONE]. Content and tool-call chunks continue to arrive as they are generated. Explicit zero usage incurs no token charge. Missing or invalid usage is not replaced with an estimate or a fixed fee.

If usage or completion cannot be verified, the API returns usage_unverified (HTTP 502) and retains reserved credits for review. settlement_pending (HTTP 503) means accounting will be retried without invoking the model again. After a stream has started, these errors appear as a final SSE error event without [DONE].

Send Idempotency-Key to identify a purchase. Reusing an accepted key returns request_already_accepted (409); changing its request content returns idempotency_conflict (409). Neither executes the model again. An initial insufficient-balance rejection (402) can be retried with the same key after funding. Do not create a new key to automatically retry a request whose outcome or settlement is pending.

Compatibility

The request shape intentionally follows OpenAI Chat Completions. Most server-side clients can migrate by changing the base URL and API key, then selecting a Xenodia model ID from Model Discovery.

The current gateway response exposes the normalized fields it persists from the model response: id, choices[].message, and usage. Do not require optional OpenAI fields such as object, created, choices[].index, or choices[].finish_reason unless your own adapter adds them.

Production guidance

• Query /v1/models before hardcoding model IDs.
• Treat model-specific parameters as optional unless the model capability data exposes them.
• Keep retries conservative for non-idempotent workflows.
• Log request IDs and status codes, not raw prompts or API keys.

Public responses expose Xenodia model identifiers and standard token counters, including supported token-detail counters. Treat usage as usage information; use your Xenodia call history for charges. Call history includes request status and Xenodia billing amounts. Route choices use stable IDs and neutral labels; applications should not depend on additional diagnostic fields.