Developer API 接口说明

API Base URL：https://xaporia.com/v1

登录后进入 Dashboard → Developer API Keys 创建密钥。完整密钥只显示一次；数据库仅保存 SHA-256 哈希。请放在服务端环境变量中，不要提交到代码或放进浏览器。

使用 Authorization: Bearer YOUR_XAPORIA_API_KEY。为确保同一逻辑请求重试不会再次创建计费请求，请自行生成并复用稳定的 Idempotency-Key。它为可选项以兼容 OpenAI 客户端；不提供时，每次重试都会视为新请求，可能再次计费。相同 Key 的重放返回 409（不会再次调用或扣款，也不会回放原响应）；相同 Key 配不同参数也返回冲突。

POST /chat/completions。支持 system/user/assistant 文本消息、temperature、top_p、max_tokens/max_completion_tokens 和 stream。单请求最多 64 条消息，正文上限 1 MiB。当前 Gateway 不支持 stop、frequency_penalty、presence_penalty、工具调用和多模态输入；不支持的采样参数会明确报错。

curl https://xaporia.com/v1/chat/completions \
  -H 'Authorization: Bearer xap_你的密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-attempt-1' \
  -d '{"model":"xaporia-mock","messages":[{"role":"user","content":"Hello, Xaporia!"}]}'

JavaScript / TypeScript（使用 OpenAI SDK）：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAPORIA_API_KEY,
  baseURL: "https://xaporia.com/v1",
});

// Reuse this value when retrying the same logical request.
const idempotencyKey = crypto.randomUUID();
const completion = await client.chat.completions.create({
  model: "xaporia-mock",
  messages: [{ role: "user", content: "Hello, Xaporia!" }],
  stream: false,
}, { headers: { "Idempotency-Key": idempotencyKey } });
console.log(completion.choices[0]?.message.content, completion.usage);

使用 Python 标准库发送非流式请求：

import json
import os
import urllib.request

payload = {"model": "xaporia-mock", "messages": [{"role": "user", "content": "你好"}]}
request = urllib.request.Request(
    "https://xaporia.com/v1/chat/completions",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["XAPORIA_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "unique-key-for-this-logical-request",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

同一逻辑请求重试时复用幂等键；每个新请求使用唯一键。示例模型仅用于格式说明，请先查询 /v1/models 获取当前可用模型。

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1793500000,
  "model": "xaporia-mock",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

设置 stream: true 后返回 text/event-stream。内容以 OpenAI Chat Completion chunk 发送，usage 在流结束附近发送，最后为 data: [DONE]。OpenAI SDK 示例：

// Reuse this value when retrying the same logical request.
const idempotencyKey = crypto.randomUUID();
const stream = await client.chat.completions.create({
  model: "xaporia-mock",
  messages: [{ role: "user", content: "Count from one to three." }],
  stream: true,
  stream_options: { include_usage: true },
}, { headers: { "Idempotency-Key": idempotencyKey } });

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
  if (chunk.usage) console.log("\nUsage:", chunk.usage);
}

SSE 线格式示例：

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":8,"completion_tokens":3,"total_tokens":11}}

data: [DONE]

GET /v1/models 只列出当前 enabled 且有有效价格的公开模型，不包含供应商路由信息。

curl https://xaporia.com/v1/models \
  -H 'Authorization: Bearer xap_你的密钥'

• invalid_api_key（401）：缺少、错误或已禁用密钥。
• insufficient_quota（402）：钱包可用余额不足。
• model_unavailable（404）：模型不存在、禁用或当前无有效价格。
• idempotency_conflict / idempotency_replay（409）：幂等键参数冲突或请求已处理。
• rate_limit_exceeded（429）：单个 Key 每分钟最多 60 次请求。
• invalid_request（400）：请求格式或参数不受支持。

Web Chat 和 Developer API 共用 USD 钱包、AI Gateway 和 Billing Engine。请求前按当前价格快照冻结预估费用；收到经过校验的实际 usage 后按 Token 实际成本结算并释放剩余冻结额。余额不足时不会调用模型。调用结果或 usage 不确定（例如流中断）时，冻结金额保持 RESERVED 等待对账，不会臆测零成本。Mock 模型的价格仅用于测试，不代表商业价格。