Skip to main content
Ace Data Cloud 提供 TypeScript / Python / Go 三種語言的官方客戶端 SDK,把 api.acedata.cloud 上的 chat completions、images、video、music、search、x402 等能力封裝成強類型方法,省去手寫 HTTP、SSE、任務輪詢、錯誤處理和重試退避的工作。 本章按真實接入順序組織:先在控制台拿到 API Token,再選語言看對應章節,最後看任務輪詢、流式響應和 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 篡改。

推薦閱讀順序

  1. TypeScript SDK 接入教程 —— npm install 之後第一段可以跑起來的代碼。
  2. Python SDK 接入教程 —— 同步、異步、流式三套用法。
  3. Go SDK 接入教程 —— Go 風格的 context.Context 和 channel 流式。
  4. SDK 任務輪詢與流式響應 —— TaskHandle 單位差異、SSE 實現細節、重試退避。
  5. SDK + X402 支付鉤子 —— 無 token,按調用上鏈結算。

如何查看剩余额度

透過 Ace Data Cloud 控制台 - 應用列表,即可查看當前賬戶的剩余额度。 透過 Ace Data Cloud 控制台 - 使用歷史 即可查看所有使用歷史和扣費詳情。

了解更多