API 文档
OpenAI 兼容协议，零代码迁移。一个 API 接入 56+ 主流大模型。
1. 接入概览
XABLE API 完全兼容 OpenAI 接口协议。您可以使用任何 OpenAI SDK 或 HTTP 客户端，只需修改 base_url 和 api_key 即可无缝切换。
快速开始
以下三种方式任选其一：
Python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(
base_url="https://xable.com.cn/v1",
api_key="xb_live_<your-key>"
)
response = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "你好，请用中文回答"}]
)
print(response.choices[0].message.content)cURL
curl https://xable.com.cn/v1/chat/completions \
-H "Authorization: Bearer xb_live_<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{"role": "user", "content": "你好，请用中文回答"}
]
}'Node.js (OpenAI SDK)
import OpenAI from "openai"
const client = new OpenAI({
baseURL: "https://xable.com.cn/v1",
apiKey: "xb_live_<your-key>"
})
const response = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [{ role: "user", content: "你好，请用中文回答" }]
})
console.log(response.choices[0].message.content)2. 认证方式
所有 API 请求需要在 HTTP Header 中携带 Bearer Token 进行认证。Token 即您的 API Key。
获取 API Key
登录 控制台 →在「API Key」页面创建密钥。密钥前缀为 xb_live_.
安全提示：请妥善保管 API Key，不要泄露给第三方。如怀疑泄露，请在控制台禁用或删除后重新创建。
认证请求头格式
Authorization: Bearer xb_live_<your-api-key>3. API 端点
所有端点均基于 RESTful 设计，基础 URL：
https://xable.com.cn/v1
| 端点 | 方法 | 描述 |
|---|---|---|
/v1/models | GET | 获取可用模型列表 |
/v1/chat/completions | POST | 聊天补全（核心接口） |
注：请求路径中不含 /api 前缀，直接使用 /v1/...
4. 模型列表
查询所有可用模型：
请求
curl https://xable.com.cn/v1/models \
-H "Authorization: Bearer xb_live_<your-key>"| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 模型标识符（用于请求中的 model 参数） |
object | string | 固定为 "model" |
created | int | 创建时间戳 |
owned_by | string | 模型供应商 |
详细模型信息和价格请前往 模型 API 页面 查看。
5. 聊天补全
使用 /v1/chat/completions 发送对话请求。
请求示例
POST /v1/chat/completions
curl https://xable.com.cn/v1/chat/completions \
-H "Authorization: Bearer xb_live_<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{"role": "system", "content": "你是一个有用的助手"},
{"role": "user", "content": "请用中文介绍一下你自己"}
],
"temperature": 0.7,
"max_tokens": 2048,
"top_p": 1,
"frequency_penalty": 0,
"presence_penalty": 0,
"stream": false
}'6. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID，见模型列表 |
messages | array | 是 | 对话消息列表 |
temperature | number | 否 | 采样温度，0–2，默认 1 |
top_p | number | 否 | 核采样参数，0–1，默认 1 |
n | int | 否 | 生成几个回复，默认 1 |
stream | bool | 否 | 是否流式输出，默认 false |
max_tokens | int | 否 | 最大输出 token 数 |
stop | string/array | 否 | 停止词 |
frequency_penalty | number | 否 | 频率惩罚，−2 到 2，默认 0 |
presence_penalty | number | 否 | 存在惩罚，−2 到 2，默认 0 |
user | string | 否 | 用户标识（用于监控） |
Message 对象
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | system / user / assistant / tool |
content | string | 是 | 消息内容 |
name | string | 否 | 消息作者名称 |
tool_calls | array | 否 | 工具调用（assistant 角色使用） |
tool_call_id | string | 否 | 工具调用 ID（tool 角色使用） |
7. 响应格式
非流式响应返回完整 JSON：
响应示例
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1717500000,
"model": "deepseek-v4-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "我是 AI 助手，很高兴为你服务！"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 15,
"completion_tokens": 20,
"total_tokens": 35
}
}| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 请求唯一标识 |
object | string | 固定 chat.completion |
created | int | 创建时间戳 |
model | string | 使用的模型 |
choices[].message.content | string | 回复文本 |
choices[].finish_reason | string | stop / length / content_filter |
usage.prompt_tokens | int | 输入 token 数 |
usage.completion_tokens | int | 输出 token 数 |
usage.total_tokens | int | 总 token 数 |
8. 流式输出 (Streaming)
设置 stream: true 启用 Server-Sent Events (SSE) 流式输出：
Python 流式请求
from openai import OpenAI
client = OpenAI(
base_url="https://xable.com.cn/v1",
api_key="xb_live_<your-key>"
)
stream = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "你好"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")流式响应格式（每行以 data: 开头）：
SSE 流式响应
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}
data: [DONE]9. 图片生成 (Image Generation)
部分模型支持图片生成。使用 /v1/images/generations 端点，接口兼容 OpenAI 图片生成协议。
请求示例
POST /v1/images/generations
curl https://xable.com.cn/v1/images/generations \
-H "Authorization: Bearer xb_live_<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"prompt": "A futuristic city with neon lights, digital art style",
"n": 1,
"size": "1024x1024"
}'参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 图片模型 ID |
prompt | string | 是 | 图片描述文字 |
n | int | 否 | 一次生成几张，默认 1 |
size | string | 否 | 尺寸：256x256 / 512x512 / 1024x1024 |
quality | string | 否 | 质量：standard / hd（仅部分模型支持） |
Python SDK 示例
Python
from openai import OpenAI
client = OpenAI(
base_url="https://xable.com.cn/v1",
api_key="xb_live_<your-key>"
)
response = client.images.generate(
model="stable-diffusion-xl-free",
prompt="A futuristic city with neon lights",
n=1,
size="1024x1024"
)
print(response.data[0].url)10. SDK 接入指南
XABLE API 完全兼容 OpenAI 协议，您可以直接使用各语言的 OpenAI SDK。以下是主流语言的完整接入示例。
Python (推荐)
安装：pip install openai
Python 完整示例
from openai import OpenAI
client = OpenAI(
base_url="https://xable.com.cn/v1",
api_key="xb_live_<your-key>"
)
# 非流式聊天
response = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[
{"role": "system", "content": "你是一个有用的助手"},
{"role": "user", "content": "请用中文介绍 XABLE 平台"}
],
temperature=0.7,
max_tokens=1024
)
print(response.choices[0].message.content)
# 流式聊天
stream = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "你好"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")Node.js / TypeScript
安装：npm install openai
Node.js 完整示例
import OpenAI from "openai"
const client = new OpenAI({
baseURL: "https://xable.com.cn/v1",
apiKey: "xb_live_<your-key>"
})
// 非流式聊天
const response = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [
{ role: "system", content: "你是一个有用的助手" },
{ role: "user", content: "请用中文介绍 XABLE 平台" }
],
temperature: 0.7,
max_tokens: 1024
})
console.log(response.choices[0].message.content)
// 流式聊天
const stream = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [{ role: "user", content: "你好" }],
stream: true
})
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content)
}
}Go
安装：go get github.com/sashabaranov/go-openai
Go 完整示例
package main
import (
"context"
"fmt"
openai "github.com/sashabaranov/go-openai"
)
func main() {
cfg := openai.DefaultConfig("xb_live_<your-key>")
cfg.BaseURL = "https://xable.com.cn/v1"
client := openai.NewClientWithConfig(cfg)
// 非流式聊天
resp, err := client.CreateChatCompletion(
context.Background(),
openai.ChatCompletionRequest{
Model: "deepseek-v4-flash",
Messages: []openai.ChatCompletionMessage{
{Role: "system", Content: "你是一个有用的助手"},
{Role: "user", Content: "请用中文介绍 XABLE 平台"},
},
},
)
if err != nil {
panic(err)
}
fmt.Println(resp.Choices[0].Message.Content)
}Java
Maven 依赖：com.theokanning.openai-gpt3-java
Java 完整示例
import com.theokanning.openai.OpenAiService;
import com.theokanning.openai.completion.chat.*;
List<ChatMessage> messages = new ArrayList<>();
messages.add(new ChatMessage("system", "你是一个有用的助手"));
messages.add(new ChatMessage("user", "请用中文介绍 XABLE 平台"));
OpenAiService service = new OpenAiService("xb_live_<your-key>", 30);
service.setBaseUrl("https://xable.com.cn/v1");
ChatCompletionRequest request = ChatCompletionRequest.builder()
.model("deepseek-v4-flash")
.messages(messages)
.build();
service.createChatCompletion(request).getChoices()
.forEach(c -> System.out.println(c.getMessage().getContent()));11. 错误码
| HTTP 状态码 | 错误类型 | 说明 |
|---|---|---|
400 | invalid_request_error | 请求参数错误 |
401 | authentication_error | API Key 无效或未提供 |
403 | permission_error | 无权限（余额不足或未认证） |
404 | not_found | 请求的资源不存在 |
429 | rate_limit_error | 请求频率超限 |
500 | server_error | 服务端内部错误 |
503 | service_unavailable | 服务暂时不可用 |
错误响应示例
{
"error": {
"message": "Incorrect API key provided: xxx. You can find your API key at https://xable.com.cn/console.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}12. 速率限制
为保障服务稳定性，API 调用有频率限制。超出限制将返回 429 状态码。
| 项目 | 默认值 | 说明 |
|---|---|---|
| 请求频率 | 10 RPM | 每分钟最多 10 次请求 |
| 并发数 | 10 路 | 同时最多 10 个请求进行中 |
| 单请求超时 | 120 秒 | 单个请求最长等待时间 |
| 单次最大 tokens | 取决于模型 | 各模型上下文长度不同 |
企业客户可联系客服提升限制。免费用户和付费用户均通过 XABLE 自营 + 联运的算力底座提供稳定的推理服务。
13. 计费说明
XABLE 采用按量计费模式，按实际消耗的 tokens 数量实时扣费，输入输出分别计价。
计费规则
| 项目 | 说明 |
|---|---|
| 计费单位 | 每 1000 tokens（约 700-800 个汉字） |
| 最低扣费 | 每次调用最低扣费 ¥0.005 |
| 免费额度 | 注册后每日 100 次免费调用（每分钟 5 次，并发 2 路） |
| 扣费方式 | 实时从账户余额扣除，无后付费账单 |
| 余额查询 | 登录控制台查看余额和消费明细 |
价格标准
不同模型价格不同，具体价格请在 模型 API 页面 查看各模型输入/输出单价。总体来说，开源/免费模型价格最低，旗舰模型价格更高但能力更强。
💡 省钱小贴士
- • 简单任务使用开源免费模型（如 deepseek-v4-flash），无需使用旗舰模型
- • 设置合理的 max_tokens 避免超长输出
- • 使用流式输出（stream: true）可以获得更快的首字延迟
- • 企业用户可联系客服获得专属优惠价格和更高并发限制
常见问题
如何获取 API Key？
注册并登录后，在控制台「API Key」页面创建。密钥前缀为 xb_live_，创建后请立即复制保存。
API 接入协议是什么？
完全兼容 OpenAI 接口协议。支持 chat/completions 端点，兼容 OpenAI Python/Node.js SDK。
免费用户和付费用户有什么区别？
免费用户可体验基础的 AI 对话能力。付费用户（余额 > 0）享有更高的并发限制、更稳定的服务质量和全部模型权限。
计费方式是什么？
按 tokens 用量实时计费，输入输出分别计价。每次调用最低扣费 ¥0.005（0.5 厘）。
支持哪些 SDK？
兼容所有 OpenAI SDK，包括 Python、Node.js、Go、Java、.NET 等。只需修改 base_url 和 api_key。
并发限制是多少？
默认 10 路并发。企业客户可联系客服提升限制。