Chat Completions API

使用 Xenodia 的 OpenAI-compatible chat endpoint 进行服务端聊天、文本生成和 agent workflow。

使用 POST /v1/chat/completions 通过 Xenodia 进行 OpenAI-compatible 聊天和 text generation。

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 时，API 返回输入 185、输出 370、总计 555。这些数值与消费记录中的计费用量一致。

使用 stream: true 时，读取 data: [DONE] 之前最后一个非空 usage。正文和工具调用仍会逐步返回。Xenodia 返回零用量时，token 费用为零；缺失或非法用量不会被替换成估算值或固定费用。

无法核实用量或执行结果时，API 返回 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 Discovery 选择 Xenodia model ID。

当前 gateway response 暴露从模型响应中持久化的标准字段：id、choices[].message 和 usage。不要强依赖 object、created、choices[].index 或 choices[].finish_reason，除非你的 adapter 自己补充这些字段。

Production guidance

调用前先查询 /v1/models，不要硬编码未经确认的模型 ID。
除非 capability data 暴露，否则把 model-specific parameter 当成 optional。
对非幂等 workflow 保持保守 retry。
日志记录 request ID 和 status code，不记录 raw prompt 或 API key。

公开响应提供 Xenodia 模型标识与标准 token 数量，包括支持的细分计数。usage 用于查看用量，费用请以 Xenodia 调用记录为准。调用记录提供请求状态与 Xenodia 计费金额；路线选择使用稳定 ID 和中立名称，请勿依赖额外诊断字段。

Chat Completions API

本页内容