API 参考

Chat Completions 对话补全

POST /v1/chat/completions

基于消息列表创建模型响应。这是最常用的 AI 接口，支持流式输出（SSE）、多轮对话、函数调用（Function Calling）、工具使用（Tool Use）、Vision 多模态等高级功能。完全兼容 OpenAI Chat Completions API 格式。

Request Headers Required

Header	Type	Description
Authorization	string	Bearer sk-your-api-key
Content-Type	string	application/json

请求体参数 (Request Body)

Parameter	Type	Required	Default	Description
model	string	Yes	-	模型 ID，如 gpt-5.4, claude-opus-4-7, gemini-2.5-flash
messages	array	Yes	-	对话消息列表，包含 role 和 content 字段
stream	boolean	No	false	是否流式输出（SSE），设为 true 时返回 Server-Sent Events 流
temperature	number	No	1	采样温度，0-2。值越高输出越随机，越低越确定
max_tokens	integer	No	-	生成 token 最大数量
top_p	number	No	1	核采样参数，0-1。与 temperature 二选一
presence_penalty	number	No	0	存在惩罚，-2 到 2。正值鼓励新话题
frequency_penalty	number	No	0	频率惩罚，-2 到 2。降低重复内容
stop	string / array	No	null	生成停止序列，最多 4 个
tools	array	No	-	模型可调用的工具列表（Function Calling）
tool_choice	string / object	No	auto	工具选择策略：auto / none / required
response_format	object	No	-	指定响应格式，如 {"type": "json_object"}
n	integer	No	1	为每个 prompt 生成多少个 completion
logprobs	boolean	No	false	是否返回 log probabilities

Messages 结构说明

system - 系统指令，定义助手行为

user - 用户消息，支持文本或多模态

assistant - 助手回复（多轮上下文）

tool - 工具调用结果

代码示例

bash / cURL

curl -X POST "https://api.xidao.online/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! Please introduce yourself."}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key-here",
    base_url="https://api.xidao.online/v1"
)

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)

JavaScript / Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-your-api-key-here',
    baseURL: 'https://api.xidao.online/v1'
});

const response = await client.chat.completions.create({
    model: 'gpt-5.4',
    messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: 'Hello!' }
    ],
    temperature: 0.7,
    max_tokens: 1024
});

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

Python (Streaming SSE)

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Write a poem about AI"}],
    stream=True
)

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

Python (Vision 图像理解)

from openai import OpenAI
import base64

client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")

# 使用 URL 方式
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image:"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
    }]
)
print(response.choices[0].message.content)

响应示例 (Response)

JSON Response (200 OK)

{
  "id": "chatcmpl-xidao-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-5.4",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! I'm an AI assistant..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 19, "completion_tokens": 26, "total_tokens": 45}
}

Embeddings 文本嵌入

POST /v1/embeddings

将文本转换为高维向量表示（浮点数数组）。用于语义搜索、RAG（检索增强生成）、文本聚类、相似度计算、推荐系统等场景。

请求体参数

Parameter	Type	Required	Default	Description
model	string	Yes	-	text-embedding-3-small(1536维) · text-embedding-3-large(3072维) · text-embedding-ada-002(1532维)
input	string / array	Yes	-	输入文本或文本数组（最多 2048 个输入，每个最多 8192 tokens）
dimensions	integer	No	-	输出向量维度（仅 text-embedding-3 系列）
encoding_format	string	No	float	float 或 base64

text-embedding-3-small

1536 维 | 8192 tokens | 性价比最优

text-embedding-3-large

3072 维 | 8192 tokens | 高精度场景

text-embedding-ada-002

1532 维 | 经典模型

代码示例

Python (基础用法)

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello, world!"
)

vector = response.data[0].embedding
print(f"Dimension: {len(vector)}")  # 1536

cURL

curl -X POST "https://api.xidao.online/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"model":"text-embedding-3-small","input":"Your text here"}'

Python (批量)

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")

texts = ["文本一", "Text two", "第三段文本"]
response = client.embeddings.create(model="text-embedding-3-small", input=texts)
vectors = [item.embedding for item in response.data]
print(f"Generated {len(vectors)} vectors")

Python (余弦相似度)

from openai import OpenAI
import numpy as np

client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")

def get_embedding(text):
    r = client.embeddings.create(model="text-embedding-3-small", input=text)
    return np.array(r.data[0].embedding)

def cosine(a, b):
    return np.dot(a,b) / (np.linalg.norm(a)*np.linalg.norm(b))

sim = cosine(get_embedding("我喜欢苹果"), get_embedding("我爱水果"))
print(f"Similarity: {sim:.4f}")

响应示例

JSON Response (200 OK)

{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.0023,-0.0091,...]}],"model":"text-embedding-3-small","usage":{"prompt_tokens":4,"total_tokens":4}}

Audio 音频处理

STT + TTS

音频处理接口包含两个核心功能：语音转文字（Speech-to-Text, STT）和文字转语音（Text-to-Speech, TTS）。支持 Whisper 语音识别和 TTS-1/TTS-1-HD 语音合成。

STT

Speech-to-Text 语音识别
POST /v1/audio/transcriptions

请求参数

Parameter	Type	Required	Description
file	file	Yes	音频文件（mp3, mp4, wav, webm 等）
model	string	Yes	whisper-1
language	string	No	ISO-639-1 语言代码（如 zh, en），留空自动检测
response_format	string	No	json/text/srt/verbose_json

bash

curl -X POST "https://api.xidao.online/v1/audio/transcriptions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F file="@recording.mp3" \
  -F model="whisper-1" \
  -F language="zh"

Python

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")
audio_file = open("recording.mp3", "rb")
result = client.audio.transcriptions.create(model="whisper-1", file=audio_file, language="zh", response_format="text")
print(result.text)

TTS

Text-to-Speech 语音合成
POST /v1/audio/speech

请求参数

Parameter	Type	Required	Default	Description
model	string	Yes	-	tts-1 或 tts-1-hd
input	string	Yes	-	要转换的文本（最大 4096 字符）
voice	string	Yes	-	声音选择
response_format	string	No	mp3	mp3/opus/aac/flac/wav
speed	number	No	1.0	语速：0.25 ~ 4.0

可用音色 (Voices)

alloy中性柔和

echo沉稳男声

fable英伦叙事

onyx低沉有力

nova活泼女声

shimmer温柔女声

Python

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")
response = client.audio.speech.create(model="tts-1-hd", voice="alloy", input="你好，欢迎使用！", response_format="mp3")
with open("output.mp3", "wb") as f:
    for chunk in response.iter_bytes(chunk_size=1024): f.write(chunk)

cURL

curl -X POST "https://api.xidao.online/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"alloy","input":"Hello world"}' \
  --output speech.mp3

Python (Streaming)

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")
with client.audio.speech.with_streaming_response.create(model="tts-1", voice="nova", input="Streaming test") as resp:
    resp.stream_to_file("output.mp3")

Images 图像生成

POST /v1/images/generations

根据文本描述生成图像。支持 DALL·E 3、Midjourney、Stable Diffusion、Flux 等模型。

代码示例

Python (DALL-E 3)

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")
response = client.images.generate(model="dall-e-3", prompt="A sunset over ocean", n=1, size="1024x1024", quality="hd")
print(response.data[0].url)

cURL

curl -X POST "https://api.xidao.online/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"model":"dall-e-3","prompt":"A cat with sunglasses","size":"1024x1024"}'

Completions 文本补全

POST /v1/completions

传统的文本补全接口。给定提示文本，模型继续生成后续文本。推荐优先使用 Chat Completions。

cURL

curl -X POST "https://api.xidao.online/v1/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"model":"gpt-5.4","prompt":"The quick brown fox","max_tokens":50}'

Moderations 内容审查

POST /v1/moderations

cURL

curl -X POST "https://api.xidao.online/v1/moderations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"input":"Test content"}'

Rerank 文档重排序

POST /v1/rerank

Python (requests)

import requests

response = requests.post(
    "https://api.xidao.online/v1/rerank",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "rerank-v1",
        "query": "What is machine learning?",
        "documents": [
            "Machine learning is a subset of artificial intelligence.",
            "Python is a popular programming language.",
            "Deep learning uses neural networks with multiple layers."
        ],
        "top_n": 3
    }
)

results = response.json()
for r in results["results"]:
    print(f"Doc {r['index']}: {r['relevance_score']:.4f}")

Anthropic Messages (Claude 原生格式)

POST /v1/messages · Base URL: https://api.xidao.online

提示：使用 Anthropic 原生格式时，认证方式为 x-api-key header 而非 Authorization: Bearer。

Authentication Headers

Header	Value	Description
x-api-key	sk-xxxxxx	API Key
anthropic-version	2023-06-01	API Version

cURL

curl -X POST "https://api.xidao.online/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-4-7","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'

Gemini Native (Google 原生格式)

OpenAI 兼容格式调用 Gemini

提示：XiDao Api 支持两种方式使用 Gemini：① OpenAI 兼容格式（推荐）② Google GenAI SDK。

方式一：OpenAI 兼容格式 (推荐)

Python

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.xidao.online/v1")
resp = client.chat.completions.create(model="gemini-2.5-flash", messages=[{"role":"user","content":"Hello!"}])
print(resp.choices[0].message.content)

gemini-2.5-pro

最新旗舰 | 复杂推理 | 1M context

gemini-2.5-flash

高效快速 | 实时应用 | 性价比最优

gemini-2.0-flash

多模态 | 图像/视频理解 | 工具调用

原生多模态

内置图像/视频/音频理解

Function Calling

原生函数调用支持

长文本处理

最高 1M+ tokens 上下文

Grounding

实时搜索增强

Realtime 实时语音对话

WebSocket · wss://api.xidao.online/v1/realtime

基于 WebSocket 的实时双向语音对话接口，适用于实时语音助手、客服机器人等场景。

注意：Realtime API 使用 WebSocket 协议，需要 WebSocket 客户端库连接。

Python (websockets)

import asyncio, websockets, json
async def chat():
    async with websockets.connect("wss://api.xidao.online/v1/realtime?model=gpt-5.4-realtime",
        additional_headers={"Authorization":"Bearer sk-your-key"}) as ws:
        await ws.send(json.dumps({"type":"session.update","session":{"modalities":["text","audio"]}}))
        async for msg in ws: print(json.loads(msg).get("type"))
asyncio.run(chat())

Videos 视频生成

POST /v1/videos/generations

根据文本描述生成视频。支持 Sora、Kling、Runway Gen-3 等模型。

cURL

curl -X POST "https://api.xidao.online/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"model":"sora","prompt":"A cat in garden","duration":10}'

Models 模型列表

GET /v1/models

cURL

curl "https://api.xidao.online/v1/models" -H "Authorization: Bearer sk-your-api-key"

Error Codes 错误码

Status	Error Type	Meaning	Solution
400	invalid_request_error	Invalid request parameters	Check request format and fields
401	authentication_error	Invalid or missing API key	Verify your API key
402	insufficient_quota	Insufficient balance	Top up your balance
404	not_found	Model not found	Check model ID spelling
429	rate_limit_exceeded	Rate limit exceeded	Reduce frequency, retry later
500	server_error	Internal server error	Retry or contact support

Base URL（基础地址）

Chat Completions 对话补全

请求体参数 (Request Body)

Messages 结构说明

代码示例

响应示例 (Response)

Embeddings 文本嵌入

请求体参数

代码示例

响应示例

Audio 音频处理

请求参数

请求参数

可用音色 (Voices)

Images 图像生成

代码示例

Completions 文本补全

Moderations 内容审查

Rerank 文档重排序

Anthropic Messages (Claude 原生格式)

Gemini Native (Google 原生格式)

方式一：OpenAI 兼容格式 (推荐)

Realtime 实时语音对话

Videos 视频生成

Models 模型列表

Error Codes 错误码