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 工具；另一份是可直接貼給 AI 程式設計 Agent 的單一 markdown 檔案。兩者都由這些頁面重新生成，因此不會與你正在看的內容脫節。

openapi.json

OpenAPI 3.1——包含文件中的每一個路徑、參數和錯誤回應。

llms-full.txt

完整的介面契約，單一 markdown 檔案，大小適合放進 Agent 的上下文視窗。

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，支援選用 webhook。
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 或錯誤訊息傳給我們，我們來查。

上一頁上傳檔案下一頁非同步任務