api.acedata.cloud 上的 chat completions、images、video、music、search、x402 等能力封裝成強類型方法,省去手寫 HTTP、SSE、任務輪詢、錯誤處理和重試退避的工作。
本章按真實接入順序組織:先在控制台拿到 API Token,再選語言看對應章節,最後看任務輪詢、流式響應和 X402 鏈上支付的高級用法。
倉庫與包
- SDK 源碼(monorepo):https://github.com/AceDataCloud/SDK
- TypeScript:
@acedatacloud/sdk - Python:
acedatacloud - Go:
github.com/AceDataCloud/SDK/go - X402 客戶端(TypeScript):
@acedatacloud/x402-client - X402 客戶端(Python):
acedatacloud-x402
三語言能力矩陣
Go SDK 的多媒體資源和任務輪詢目前處於 alpha 階段(偽版本v0.0.0-20260505072132-4a3d921f9bb4),穩定的能力是chat.completions。多媒體場景請優先選 TypeScript 或 Python。
何時用 SDK / MCP / 原生 HTTP / X402
SDK 與 X402 不互斥:SDK 同時支持「token 路徑」和「
paymentHandler 路徑」,詳見 SDK + X402 支付鉤子。
申請 API Token
要使用 SDK,首先到 Ace Data Cloud 控制台 - 應用列表 申請一個 API Token:
如果你尚未登錄或註冊,會自動跳轉到登錄頁面邀請你來註冊和登錄,登錄註冊之後會自動返回當前頁面。
在首次申請時會有免費額度贈送,可以免費體驗 Ace Data Cloud 提供的各種 AI 服務。
複製剛才拿到的 Token,下面統一記作 {token}。
統一環境變量
三種語言的 SDK 都會自動讀取同一個環境變量ACEDATACLOUD_API_TOKEN,推薦在 shell 裡 export,讓 SDK 自動拾取:
- TypeScript:
new AceDataCloud({ apiToken: '{token}' }) - Python:
AceDataCloud(api_token="{token}") - Go:
adc.NewClient(adc.WithAPIToken("{token}"))
注意:AceDataCloud 項目倉庫裡約定俗成是ACEDATACLOUD_API_KEY(在.env/ CI 裡),但這三個 SDK 本身只識別ACEDATACLOUD_API_TOKEN。如果你的環境裡只有ACEDATACLOUD_API_KEY,請在構造時顯式傳入。
30 秒上手三例
下面三段代碼做的是同一件事:調用gpt-4o-mini,讓它只回覆 ADC_*_OK。每段都附了真實運行結果,可以拿你自己的 token 復現。
TypeScript
SDK 當前把響應聲明為程序運行結果:Record<string, unknown>,運行時是一個普通 JSON 對象,可以直接按字段訪問。在嚴格 TS 項目裡如果遇到類型報錯,可以臨時as any,或者參考 SDK 任務輪詢與流式響應 自定義 typed wrapper。
Python
Python SDK 當前返回的是程序運行結果:dict,所以用res["id"]而不是res.id。這一點和openai-python不同,遷移時需要注意。
Go
Go SDK 的響應統一是程序運行結果:map[string]any,沒有強類型 struct,需要自行類型斷言。所有資源訪問器都是方法鏈:client.OpenAI().Chat().Completions().Create(...)。
id、elapsed_ms、usage 來源都一致:經 PlatformGateway 鑑權 → 目標 OpenAI 兼容 API → 寫入計費記錄。content 字段是模型真實輸出,用固定標識 ADC_*_OK 是為了證明響應沒有被 SDK 篡改。
推薦閱讀順序
- TypeScript SDK 接入教程 ——
npm install之後第一段可以跑起來的代碼。 - Python SDK 接入教程 —— 同步、異步、流式三套用法。
- Go SDK 接入教程 —— Go 風格的
context.Context和 channel 流式。 - SDK 任務輪詢與流式響應 —— TaskHandle 單位差異、SSE 實現細節、重試退避。
- SDK + X402 支付鉤子 —— 無 token,按調用上鏈結算。
如何查看剩余额度
透過 Ace Data Cloud 控制台 - 應用列表,即可查看當前賬戶的剩余额度。 透過 Ace Data Cloud 控制台 - 使用歷史 即可查看所有使用歷史和扣費詳情。了解更多
- 📦 SDK monorepo 源碼
- 🔌 X402 集成指南
- 🛠 MCP Servers 教程
- 📊 服務列表與定價

