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 控制台 - 使用历史 即可查看所有使用历史和扣费详情。

了解更多