API DOCUMENTATION

API 文档

完全兼容 OpenAI Python / Node SDK,把 base_url 替换成下方地址即可使用全部模型。

Base URL https://api.xsai5.xyz/v1
鉴权 Authorization: Bearer xsai_sk_…

5 分钟入门

三步跑通你的第一个请求。

  1. 1. 获取 API 密钥

    登录后进入控制台 → API 密钥,新建一把密钥,复制完整 xsai_sk_… 字符串。

  2. 2. 选择模型

    API 中转找到目标模型,复制它的 publicModelId(例如 gpt-5claude-3.5-sonnetgemini-1.5-pro)。

  3. 3. 发送请求

    下面是用官方 OpenAI SDK 调用的最小示例:

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.xsai5.xyz/v1",
    api_key="xsai_sk_…",
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "你好,介绍一下你自己。"},
    ],
)
print(response.choices[0].message.content)

鉴权

所有请求必须在 HTTP Header 里带上 Bearer Token:

Authorization: Bearer xsai_sk_xxxxxxxxxxxxxxxxxxxxxxxx
  • 密钥以 xsai_sk_ 为前缀,仅在创建/重置那一刻可在控制台看到完整明文。
  • 每把密钥可单独配置 额度上限过期时间允许的模型白名单,详见控制台「API 密钥」标签页。
  • 密钥泄露请立即在控制台「重置」即可生成新密钥并自动失效旧密钥。

Base URL

统一入口:

https://api.xsai5.xyz/v1

所有端点路径都拼在这之后。例如对话补全完整地址为 https://api.xsai5.xyz/v1/chat/completions

模型列表 · GET /v1/models

列出当前账户可调用的全部公开模型。响应格式与 OpenAI 完全一致。

models = client.models.list()
for m in models.data:
    print(m.id)

响应示例:

{
  "object": "list",
  "data": [
    { "id": "gpt-5",            "object": "model", "owned_by": "openai" },
    { "id": "claude-3.5-sonnet","object": "model", "owned_by": "anthropic" }
  ]
}

对话补全 · POST /v1/chat/completions

主力端点,覆盖文本对话、流式输出、工具调用、视觉理解、推理模型。

请求参数

  • model string · 必填 — 见 模型列表 返回的 id
  • messages array · 必填 — OpenAI 标准 messages 数组
  • stream boolean — true 时返回 SSE 流式响应,详见 流式响应
  • tools array — function calling,详见 工具调用
  • temperature / top_p / max_tokens 等所有 OpenAI 兼容参数原样转发

最小示例

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "你是个资深的 Python 工程师。"},
        {"role": "user",   "content": "用 Python 写一个快速排序。"},
    ],
    temperature=0.7,
    max_tokens=1000,
)
print(response.choices[0].message.content)

响应示例

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 240,
    "total_tokens": 272
  }
}

图像生成 · POST /v1/images/generations

同步图像生成端点,参数与 OpenAI Images API 一致。

response = client.images.generate(
    model="gpt-image-1",
    prompt="A cat playing piano in space, watercolor style",
    size="1024x1024",
    n=1,
)
print(response.data[0].url)

透明背景 · background

需要一张可以直接叠到别的画面上的图(商品图、图标、贴纸)时,加 background: "transparent"

curl https://api.xsai5.xyz/v1/images/generations \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴墨镜的柴犬,纯净主体,无背景",
    "background": "transparent",
    "output_format": "png"
  }'
  • transparent 出透明底;opaque 强制不透明底;auto(默认)由模型自己决定。
  • 必须配 output_format: "png""webp"。JPEG 没有透明通道,配 transparent 会被直接拒绝 —— 我们宁可报错,也不给你一张看起来对、其实是白底的图。
  • 不是所有图像模型都支持指定背景。目前支持的是 gpt-image-2;不支持的模型会在请求时直接返回错误并说明,不会扣费出一张背景不对的图。

异步任务模式可通过 POST /v1/images/jobs 创建任务、GET /v1/images/jobs/{id} 轮询结果,适合长时间生成场景。

视频生成 · POST /v1/videos

异步任务:创建后返回任务 id,轮询到完成为止。视频按秒计费,参数选错的代价比图像大得多,所以先查能力再下单

先查这个模型认哪些参数 · GET /v1/videos/capabilities

每个视频模型认的时长档位、画幅、分辨率、参考素材上限各不相同,而且会随渠道变。这个端点返回当前真实生效的一份,不要把参数写死在你的代码里。

curl https://api.xsai5.xyz/v1/videos/capabilities \
  -H "Authorization: Bearer xsai_sk_…"

返回里每个模型一张卡片:

  • duration.options — 认哪些秒数;duration.fixed 为 true 表示时长不可调,别发 seconds
  • aspectRatio.options / resolution.optionsnull 表示未声明,那就一个都别发:中转会原样透传,上游可能自己截一个再照常计费
  • reference.images / videos / audios — 参考素材各自的数量上限、体积上限与格式
  • reference.firstLastFrame — 是否支持首尾帧,mustPair 为 true 时必须首尾同时给
  • typicalSeconds — 这个模型近期真实的耗时分位数(p50 / p90),样本不足时为 null,用来给用户一个合理的等待预期
  • maintained — 为 false 表示我们还没为它填能力声明,此时参数一律透传由上游裁决

响应带 ETag,可用 If-None-Match 做条件请求,内容不变时返回 304。

创建任务

curl https://api.xsai5.xyz/v1/videos \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "清晨山谷薄雾流动,阳光穿透林间,镜头平稳前推",
    "seconds": 4,
    "aspect_ratio": "16:9"
  }'

返回 202 与任务 id,随后轮询 GET /v1/videos/{id},直到 status 变成 succeededfailed。响应里的 retry_after_seconds 是建议的轮询间隔。

参考素材与首尾帧

先用 POST /v1/filesmultipart/form-data)上传,拿到 file_nexai_… 的 id 再引用;也可以直接给公网可访问的 URL。

# 1) 上传参考图
curl https://api.xsai5.xyz/v1/files \
  -H "Authorization: Bearer xsai_sk_…" \
  -F purpose=user_data -F file=@first.png

# 2) 引用它(images 是参考图;首尾帧走 first_image_url / last_image_url)
curl https://api.xsai5.xyz/v1/videos \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "以参考图为起点,镜头缓缓拉远",
    "seconds": 4,
    "images": ["file_nexai_…"]
  }'

首尾帧与普通参考素材互斥(上游普遍如此):用了 first_image_url / last_image_url 就不要再传 images / videos / audios。是否支持、是否必须成对,以 reference.firstLastFrame 为准。

参数不合法的任务不计费:中转先受理再校验,作业会转 failed 并带上原因,deducted_units 为 0。

流式响应

在请求体里加 "stream": true,服务器将以 Server-Sent Events 形式逐个 token 推送增量。

stream = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "讲一个简短的故事"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
  • 响应 Content-Type 为 text/event-stream,每条事件 data: {json}\n\n
  • 结束事件为 data: [DONE]
  • 计费仍按总 token 计算,与非流式一致

工具调用(Function Calling)

所有支持工具调用的模型(GPT-5 / Claude 3.5+ / Gemini 1.5+ 等)原生兼容 OpenAI tools 格式。

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询某城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "北京今天天气怎么样?"}],
    tools=tools,
    tool_choice="auto",
)
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

视觉理解

支持视觉的模型(带 vision 能力标记)可以在 messages.content 里放图片:

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/photo.jpg"
            }}
        ]
    }],
)
print(response.choices[0].message.content)

图片可以是 公开 URLbase64 data URIdata:image/jpeg;base64,…)。

错误码

所有错误响应遵循 OpenAI 错误格式:

{
  "error": {
    "message": "API 密钥已过期",
    "type": "authentication_error",
    "code": "key_expired"
  }
}
HTTPcode说明
401authentication_error缺少 / 无效 / 已过期的 API 密钥
402insufficient_quota账户余额不足,或密钥额度已用尽
403permission_error密钥未授权调用此模型(白名单限制)
404model_not_found模型不存在
429rate_limit_exceeded触发并发限流
500api_error中转内部错误
502upstream_error上游返回错误
503model_channel_unavailable当前模型暂无可用上游通道
504timeout上游请求超时

计费与限流

计费

  • 所有模型按 真实 token / 张数 实时扣费,单价见API 中转
  • 缓存命中部分(prompt_tokens_details.cached_tokens)按对应模型的"缓存输入"价计费
  • 失败请求 不扣费
  • 每条请求扣费可在请求记录逐条核对

限流

  • 用户级、密钥级、单模型通道级三段并发限制(详见控制台设置)
  • 触发限流时返回 429 rate_limit_exceeded,建议指数退避重试

密钥级限制

每把密钥可在控制台单独配置:

  • 额度上限:达到金额上限后该密钥停止扣费,账户其他密钥不受影响
  • 过期时间:到期后自动失效
  • 允许的模型白名单:仅勾选的模型可被该密钥调用,触发其他模型返回 403