Chat Completions API

POST /v1/chat/completions は Xenodia 経由の OpenAI-compatible チャットと text generation endpoint です。

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.prompt_tokens と usage.completion_tokens は Xenodia の課金対象 token 数です。適用される token 倍率を反映し、それぞれを丸めた値を返します。usage.total_tokens は両者の合計です。クライアント側で倍率を再度適用しないでください。

例えば、入力 100 token、出力 200 token、倍率 1.85 の場合、入力 185、出力 370、合計 555 を返します。これらは利用履歴に記録される課金対象の数量と一致します。

stream: true では、data: [DONE] より前に返される最後の非 null usage を読み取ってください。本文とツール呼び出しは引き続き順次返されます。明示的なゼロ使用量の token 料金はゼロです。使用量が欠落または不正な場合、推定値や固定料金には置き換えません。

使用量や実行結果を確認できない場合は usage_unverified（HTTP 502）を返し、予約済み credit を確認待ちとして保持します。settlement_pending（HTTP 503）では、モデルを再実行せず会計処理のみを再試行します。ストリーム開始後は SSE エラーイベントを返し、[DONE] は送りません。

購入単位で Idempotency-Key を指定できます。受付済みのキーは request_already_accepted（409）、異なる内容での再使用は idempotency_conflict（409）となり、モデルは再実行されません。最初の残高不足（402）は入金後に同じキーで再試行できます。結果や決済が確認待ちの場合、新しいキーで自動的に再実行しないでください。

Compatibility

Request shape は OpenAI Chat Completions に合わせています。多くの場合、base URL、API key、model ID を変更し、Model Discovery から Xenodia model ID を選ぶだけで移行できます。

現在の gateway response は model response から保存する標準フィールド id、choices[].message、usage を返します。object、created、choices[].index、choices[].finish_reason は自前 adapter が追加しない限り必須にしないでください。

Production guidance

• model ID を固定する前に /v1/models を問い合わせる。
• capability data が公開していない model-specific parameter は optional として扱う。
• 非冪等 workflow の retry は控えめにする。
• raw prompt や API key ではなく request ID と status code を記録する。