Skip to main content
Ace Data Cloud provides official client SDKs in TypeScript / Python / Go, encapsulating capabilities such as chat completions, images, video, music, search, x402, etc., available at api.acedata.cloud, into strongly typed methods, eliminating the need for manual HTTP, SSE, task polling, error handling, and retry backoff work. This chapter is organized in the order of actual integration: first obtain the API Token from the console, then select the language to view the corresponding section, and finally look at advanced usage of task polling, streaming responses, and X402 on-chain payments.

Repositories and Packages

Capability Matrix for Three Languages

The multimedia resources and task polling of the Go SDK are currently in alpha stage (pseudo version v0.0.0-20260505072132-4a3d921f9bb4), with stable capabilities being chat.completions. For multimedia scenarios, please prioritize TypeScript or Python.

When to Use SDK / MCP / Native HTTP / X402

SDK and X402 are not mutually exclusive: the SDK supports both “token path” and “paymentHandler path”, see SDK + X402 Payment Hook.

Applying for API Token

To use the SDK, first apply for an API Token at Ace Data Cloud Console - Application List: If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after logging in or registering, you will be automatically returned to the current page. You will receive a free quota upon your first application, allowing you to experience various AI services provided by Ace Data Cloud for free. Copy the Token you just obtained, which will be referred to as {token} below.

Unified Environment Variable

The SDKs in the three languages will automatically read the same environment variable ACEDATACLOUD_API_TOKEN, and it is recommended to export it in the shell, allowing the SDK to pick it up automatically:
You can also explicitly pass it when constructing the client, with the corresponding parameter names for the three languages being:
  • TypeScript: new AceDataCloud({ apiToken: '{token}' })
  • Python: AceDataCloud(api_token="{token}")
  • Go: adc.NewClient(adc.WithAPIToken("{token}"))
Note: The convention in the AceDataCloud project repository is ACEDATACLOUD_API_KEY (in .env / CI), but these three SDKs only recognize ACEDATACLOUD_API_TOKEN. If your environment only has ACEDATACLOUD_API_KEY, please pass it explicitly during construction.

30 Seconds to Get Started with Three Examples

The following three code snippets do the same thing: call gpt-4o-mini and have it reply with ADC_*_OK exactly. Each snippet includes actual running results, which you can reproduce with your own token.

TypeScript

The SDK currently declares the response as Record<string, unknown>, and at runtime it is a regular JSON object that can be accessed directly by fields. In strict TS projects, if you encounter type errors, you can temporarily use as any, or refer to SDK Task Polling and Streaming Responses to create a custom typed wrapper.
Program running result:

Python

The current return of the Python SDK is dict, so use res["id"] instead of res.id. This is different from openai-python, so be careful during migration.
Program running result:

Go

The Go SDK response is uniformly map[string]any, without strong typed struct, requiring manual type assertion. All resource accessors are method chains: client.OpenAI().Chat().Completions().Create(...).
Program running result:
The id, elapsed_ms, and usage in the responses of the three languages come from the same source: authenticated by PlatformGateway → target OpenAI compatible API → write billing records. The content field is the actual output of the model, using a fixed identifier ADC_*_OK to prove that the response has not been tampered with by the SDK.
  1. TypeScript SDK Integration Tutorial —— Code that can run after npm install.
  2. Python SDK Integration Tutorial —— Three sets of usage: synchronous, asynchronous, and streaming.
  3. Go SDK Integration Tutorial —— Go style context.Context and channel streaming.
  4. SDK Task Polling and Streaming Response —— Differences in TaskHandle units, SSE implementation details, and retry backoff.
  5. SDK + X402 Payment Hook —— No token, on-chain settlement based on calls.

How to Check Remaining Quota

You can check the current account’s remaining quota through the Ace Data Cloud Console - Application List. You can view all usage history and billing details through the Ace Data Cloud Console - Usage History.

Learn More