Developer API guide

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

Sign in and open Dashboard → Developer API Keys. Full keys appear once; only SHA-256 hashes are stored. Keep keys in server environment variables, never in source code or browsers.

Use Authorization: Bearer YOUR_XAPORIA_API_KEY. To avoid creating another billable request on retry, generate and reuse a stable Idempotency-Key. This is optional for OpenAI client compatibility. Without it, retries are new requests and may incur charges. Replays return 409 without another call or charge, and do not replay the response. Reusing a key with different parameters also conflicts.

POST /chat/completions. Supports system/user/assistant text messages, temperature, top_p, max_tokens/max_completion_tokens and stream. Up to 64 messages and 1 MiB per request. This Gateway does not support stop, frequency_penalty, presence_penalty, tools or multimodal input; unsupported sampling parameters return explicit errors.

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);

Send a non-streaming request using the Python standard library:

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))

Reuse the idempotency key for retries; use a unique key for each new request. Example model IDs illustrate the format; query /v1/models for available 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 }
}

Settingsstream: true returns text/event-stream. Content uses OpenAI Chat Completion chunks. Usage arrives near the end, followed by data: [DONE]. OpenAI SDK example:

// 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 wire format example:

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 lists enabled public models with valid pricing, without provider routing details.

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

• invalid_api_key (401): Missing, invalid or disabled API key.
• insufficient_quota (402): Insufficient available wallet balance.
• model_unavailable (404): Model missing, disabled or without valid pricing.
• idempotency_conflict / idempotency_replay (409): Idempotency conflict or request already processed.
• rate_limit_exceeded (429): Up to 60 requests per minute per key.
• invalid_request (400): Unsupported request format or parameters.

Web Chat and Developer API share the USD wallet, AI Gateway and Billing Engine. Estimated charges are reserved using a price snapshot. Validated usage settles actual Token charges and releases the remainder. Insufficient funds prevent model calls. Uncertain results or usage remain RESERVED for reconciliation, never assumed free. Mock prices are for testing only.