Ship your first request through one API.

01 · ORIENTATION

Welcome

XiaoqilinAPI provides an OpenAI-compatible gateway so applications can use one authentication pattern and one endpoint while model availability stays managed in the platform.

• Keep your existing OpenAI-compatible client.
• Create and revoke API keys in Console.
• Check live model availability and pricing in Model Square.
• Use streaming, tool calls, embeddings, and image endpoints when the selected model supports them.

02 · FIRST REQUEST

Quickstart

Step 1 — Create an API key

Sign in to Console, open API Tokens, create a key, and copy it immediately. Store it like a password.

Step 2 — Send a chat request

curl -X POST https://xiao-qilin.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>" \
  -d '{
    "model": "<MODEL_ID_FROM_MODEL_SQUARE>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Step 3 — Confirm the response

A successful request returns HTTP 200 and an OpenAI-compatible JSON response. If the model ID is rejected, copy its current ID from Model Square.

03 · SECURITY

Authentication

Send your key in the Authorization header for every API request.

Authorization: Bearer sk-<YOUR_API_KEY>

Key safety

• Keep keys in environment variables or a secret manager.
• Use separate keys for development, staging, and production.
• Never expose a key in browser code, screenshots, logs, or repositories.
• Revoke a key in Console as soon as you suspect exposure.

04 · CONTRACT

Base URL & endpoints

Production base URL: https://xiao-qilin.com/v1

Additional endpoints may appear in Console as platform capabilities evolve.

05 · ROUTING

Models

Use the exact model ID shown in Model Square. The gateway routes the request according to your account and the active channel configuration.

curl https://xiao-qilin.com/v1/models \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>"

06 · CAPACITY

Rate limits & quotas

Limits depend on your account, token, model, and active channel. Inspect the current values in Console and handle throttling explicitly.

• 429 Too Many Requests — wait and retry with exponential backoff.
• 402 — check the current account balance and billing state in Console.
• Log request IDs and usage fields so billing or reliability questions can be traced.

07 · DELIVERY

Streaming

For models that support streaming, set stream to true and consume Server-Sent Events until the final [DONE] marker.

curl -N -X POST https://xiao-qilin.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>" \
  -d '{
    "model": "<MODEL_ID>",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short welcome."}]
  }'

stream = client.chat.completions.create(
    model="<MODEL_ID>",
    stream=True,
    messages=[{"role": "user", "content": "Write a short welcome."}],
)

for chunk in stream:
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)

08 · CLIENTS

Code examples

Python · OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://xiao-qilin.com/v1",
    api_key="sk-<YOUR_API_KEY>",
)

response = client.chat.completions.create(
    model="<MODEL_ID>",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

Node.js · OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://xiao-qilin.com/v1",
  apiKey: "sk-<YOUR_API_KEY>",
});

const response = await client.chat.completions.create({
  model: "<MODEL_ID>",
  messages: [{ role: "user", content: "Hello" }],
});

console.log(response.choices[0].message.content);

09 · RESPONSE

Response format

Non-streaming chat responses follow the OpenAI-compatible choices and usage structure.

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "<MODEL_ID>",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello!"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 4,
    "total_tokens": 12
  }
}

10 · TOOLS

Function calling

When the selected model supports tools, send JSON Schema function definitions and execute returned tool calls in your application.

{
  "model": "<MODEL_ID>",
  "messages": [{"role": "user", "content": "What is the weather?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

After your code executes the function, send the result back as a tool message to continue the conversation.

11 · RECOVERY

Errors

When asking for help, include the timestamp, endpoint, HTTP status, request ID, and sanitized response body. Never include the full API key.

12 · LIVE ACCOUNT DATA

Pricing & billing

Model rates and account offers are operational data, so this guide does not freeze them into a static table.

13 · VECTOR DATA

Embeddings

Use the embeddings endpoint when an embedding model is available to your key. Copy the current model ID from Model Square.

curl -X POST https://xiao-qilin.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>" \
  -d '{
    "model": "<EMBEDDING_MODEL_ID>",
    "input": "Text to embed"
  }'

14 · MEDIA

Image generation

If an image model is enabled for your key, send generation requests through the compatible image endpoint. Supported fields vary by model.

curl -X POST https://xiao-qilin.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>" \
  -d '{
    "model": "<IMAGE_MODEL_ID>",
    "prompt": "A paper qilin under moonlight",
    "n": 1
  }'

15 · MIGRATION

Migration guide

Most OpenAI SDK integrations only need a new base URL, a XiaoqilinAPI key, and a current model ID.

Python — change the client configuration

client = OpenAI(
    base_url="https://xiao-qilin.com/v1",
    api_key="sk-<YOUR_XIAOQILIN_KEY>",
)

Node.js — change the client configuration

const client = new OpenAI({
  baseURL: "https://xiao-qilin.com/v1",
  apiKey: "sk-<YOUR_XIAOQILIN_KEY>",
});

Run an end-to-end test for streaming, tool calls, retries, and billing logs before moving production traffic.

16 · AGENT SETUP

Agent setup

Coding agents and AI assistants can use XiaoqilinAPI through the same OpenAI-compatible endpoint. Point the agent at the base URL, set an API key from Console, and pick a live model ID from Model Square.

Environment variables

Most agent CLIs and SDKs read the standard OpenAI environment variables. Set them once in your shell profile or project configuration:

export OPENAI_API_KEY="sk-<YOUR_API_KEY>"
export OPENAI_BASE_URL="https://xiao-qilin.com/v1"

Custom endpoint settings

Tools with built-in model settings (for example Cursor or similar editors) accept an OpenAI API key with a base URL override. Use the key from Console, the base URL above, and the current model ID from Model Square.

SDK configuration

For agent frameworks that call models in code, configure the client like any other OpenAI-compatible service:

from openai import OpenAI

client = OpenAI(
    base_url="https://xiao-qilin.com/v1",
    api_key="sk-<YOUR_API_KEY>",
)

Agent skill template

To onboard an agent automatically, add a short instruction file (for example CLAUDE.md or AGENTS.md) to the project root:

# CLAUDE.md - agent instructions
- Base URL: https://xiao-qilin.com/v1
- Auth: set OPENAI_API_KEY from Console
- Models: fetch live IDs via GET /v1/models
- Streaming and tools: supported when the selected model supports them

Verify the connection

Send a small request and confirm you get HTTP 200 with the expected model list or completion:

curl https://xiao-qilin.com/v1/models \
  -H "Authorization: Bearer sk-<YOUR_API_KEY>"

17 · SUPPORT

FAQ & support

Can I use the standard OpenAI SDK?

Yes. Set base_url or baseURL to XiaoqilinAPI and use your XiaoqilinAPI key.

Why is a model ID rejected?

Model availability can differ by account and channel. Copy the exact current ID from Model Square.

Does XiaoqilinAPI store my prompts?

Review the current privacy policy and platform settings for the authoritative data-handling terms.

What should I include in a support request?

Include a timestamp, endpoint, status code, request ID, and sanitized error response. Remove keys and sensitive prompt content.