aisplice

API 参考

对接说明

#基础地址

所有端点都挂在本站域名的 /v1 下。没有区域选择——到上游厂商的路由由网关内部完成。

#认证头

一个 Authorization: Bearer 头就是全部认证。没有签名、没有时间戳、也不需要任何 per-user 头——其它中转站要求的额外头这里一概不存在。

#错误结构

网关侧的拒绝使用 OpenAI 形态的错误结构，type 为 "xiaoxiang_error"。上游错误原样透传，异步任务端点返回的是扁平结构，另有两种情况完全没有响应体——写解析逻辑之前请先看错误码页。

error.json
HTTP/1.1 402 Payment Required
X-Oneapi-Request-Id: 2026091023...

{
  "error": {
    "message": "insufficient account balance, please top up to continue (request id: 2026091023...)",
    "type": "xiaoxiang_error",
    "code": "insufficient_user_quota"
  }
}

五种错误结构与完整错误码表 →

#重试建议

对 429 和 5xx 做指数退避重试，有 Retry-After 时以它为准。不要重试 4xx 校验类错误——同样的请求体只会再失败一次。对会计费的提交请带上 Idempotency-Key，这样超时后的重试会重放首次结果，而不是再开一个任务。

backoff.py
import time, requests

def call_with_backoff(url, headers, body, tries=5):
    for i in range(tries):
        r = requests.post(url, headers=headers, json=body)
        if r.status_code not in (429, 500, 502, 503, 504):
            return r
        # 429 and 413 have no JSON body — never parse before checking status.
        wait = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait)
    r.raise_for_status()

幂等键的工作方式 →

#机读规范

同一份契约的两种生成格式：OpenAPI 用于生成客户端、导入 Postman 等 API 工具；另一份是可直接粘给编码智能体的单文件 markdown。两者都由这些页面重新生成，因此不会与你正在看的内容脱节。

openapi.json

OpenAPI 3.1——包含每一个已文档化的路径、参数和错误响应。

llms-full.txt

完整的接口契约，单个 markdown 文件，体积适合放进智能体的上下文。

llms.txt

全部文档页面的简短索引，供会优先抓取它的 AI 客户端使用。

server 地址会被改写为当前域名，生成出来的客户端无需额外配置。
generate-a-client.sh
# Any OpenAPI generator works; this is the common one.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.aisplice.store/openapi.json \
  -g python \
  -o ./gateway-client

#端点总览

所有路径都接受 OpenAI 请求体——厂商特有参数（anthropic tool_use、gemini thinking_config）原样透传。厂商原生路径和冻结的历史路由单独列在兼容页。

文本
POST/v1/chat/completions多轮对话、工具调用、流式、JSON 模式。
POST/v1/responses单次文本调用，支持结构化输出与推理。
POST/v1/messagesAnthropic 原生格式——同一套认证，无需适配层。
POST/v1/responses/compact在支持 compaction 的模型上压缩长对话——没有流式形态。
向量
POST/v1/moderations内容审核，同一线格式。
音乐
POST/v1/music/generations异步音乐生成——返回 task_id，支持可选 webhook。
GET/v1/music/tasks/:task_id轮询异步音乐任务状态与进度。
GET/v1/music/tasks/:task_id/content通过网关获取最终音频结果。
图片
POST/v1/images/tasks异步出图，图片模型都走这个接口——立即返回 task_id，可选回调。
GET/v1/images/tasks/:task_id轮询异步图片任务的状态与进度。
GET/v1/images/tasks/:task_id/content获取最终图片 URL——持久链接，可放心存储。
视频
POST/v1/videosOpenAI 形状的视频生成（Sora、豆包）——支持可选 webhook。
GET/v1/videos/:task_id轮询异步任务状态；结果在 /content。
GET/v1/videos/:task_id/content通过网关下载生成完的视频。
DELETE/v1/videos/:task_id取消尚未进入终态的任务。
POST/v1/videos/:video_id/remix在支持的模型上，用新的提示词重新生成已有视频。
3D
POST/v1/model3d/tasks异步 3D 资产生成与后处理——返回 task_id。
GET/v1/model3d/tasks/:task_id轮询 3D 任务；结果 URL 直接在任务响应体里，没有 /content 路由。
素材
POST/v1/media/upload-policy为不超过对应配置上限的图片、视频、音频或通用文件创建短期上传凭证。
App 订阅
POST/v1/google-play/verify用这个 key 上配置的服务账号，查询 Google Play 购买凭证的订阅状态——免费，不调用模型。
POST/v1/xsolla/verify用这个密钥上设置的 Xsolla API 密钥，查询 Xsolla 用户有没有生效中的订阅——免费，不调用模型。
账户
GET/v1/balance账户余额和这个 key 还能花多少——免费，不调用模型。
元数据
GET/v1/models列出该密钥可用的全部模型。
GET/v1/models/:model查询单个模型——Anthropic 和 OpenAI 客户端启动时探测的就是这个结构。

还是没解决？

把请求 ID 或报错信息发给我们，我们来查。

上一页上传文件接下来异步任务