Ace Data Cloud SDK Overview

Ace Data Cloud provides official client SDKs in TypeScript / Python / Go, encapsulating the capabilities of chat completions, images, video, music, search, x402, etc., on api.acedata.cloud into strongly typed methods, saving the effort of manually handling HTTP, SSE, task polling, error handling, and retry backoff.

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

Capability TypeScript Python Go
chat.completions.create (non-streaming) ✅ ✅ ✅
chat.completions.create (SSE streaming) ✅ ✅ ✅
images.generate (Midjourney / Flux / NanoBanana / Seedream) ✅ ✅ 🚧 (alpha)
videos.generate (Sora / Veo / Luma / Kling / Hailuo / Wan) ✅ ✅ 🚧 (alpha)
audios.generate (Suno / Producer / Fish) ✅ ✅ 🚧 (alpha)
search.google (Serp) ✅ ✅ 🚧 (alpha)
TaskHandle asynchronous polling ✅ (milliseconds) ✅ (seconds) 🚧
Asynchronous client ✅ (Promise) ✅ (AsyncAceDataCloud) ✅ (context.Context)
Automatic retry + exponential backoff ✅ ✅ ✅
Typed exceptions (AuthenticationError / RateLimitError …) ✅ ✅ ✅
X402 paymentHandler hook (on-chain payment without token) ✅ ✅ ❌ (planned)

The multimedia resources and task polling of the Go SDK are currently in alpha (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

Scenario Recommended Method
Backend services, CLI, automation scripts, Agent frameworks SDK (this chapter)
MCP client calls like Claude Desktop / Cursor / Cline MCP Servers
One-time curl verification, debugging, embedded environments that only support HTTP Native HTTP (Quick Start for each service)
Do not want to create an API Token, pay USDC on the call chain X402 Integration Guide

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:

export ACEDATACLOUD_API_TOKEN={token}
# Optional: default https://api.acedata.cloud
# export ACEDATACLOUD_BASE_URL=https://api.acedata.cloud

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 AceDataCloud project repository conventionally uses ACEDATACLOUD_API_KEY (in .env / CI), but these three SDKs only recognize ACEDATACLOUD_API_TOKEN. If your environment only has ACEDATACLOUD_API_KEY, please explicitly pass it 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

import { AceDataCloud } from '@acedatacloud/sdk';

const client = new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY });

const t0 = Date.now();
const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly: ADC_TS_SDK_OK' }],
  max_tokens: 20,
  temperature: 0
});
console.log('elapsed_ms', Date.now() - t0);
console.log('id', res.id);
console.log('model', res.model);
console.log('content', res.choices[0].message.content);
console.log('usage', JSON.stringify(res.usage));

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:

elapsed_ms 2543
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQA
model gpt-4o-mini
content ADC_TS_SDK_OK
usage {"prompt_tokens":16,"completion_tokens":6,"total_tokens":22}

Python

import os, time, json
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_SDK_OK"}],
    max_tokens=20,
    temperature=0,
)
print("elapsed_ms", int((time.time() - t0) * 1000))
print("id", res["id"])
print("model", res["model"])
print("content", res["choices"][0]["message"]["content"])
print("usage", json.dumps({k: v for k, v in res["usage"].items()
                            if k in ("prompt_tokens","completion_tokens","total_tokens")}))

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:

elapsed_ms 2963
id chatcmpl-DldFdnIlhSUXINpupgsUmZL78MnBu
model gpt-4o-mini
content ADC_PY_SDK_OK
usage {"prompt_tokens": 17, "completion_tokens": 7, "total_tokens": 24}

Go

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_KEY")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Reply with exactly: ADC_GO_SDK_OK"}},
        MaxTokens: 20,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("id", res["id"])
    fmt.Println("model", res["model"])
    choices := res["choices"].([]any)
    msg := choices[0].(map[string]any)["message"].(map[string]any)
    fmt.Println("content", msg["content"])
    usage := res["usage"].(map[string]any)
    fmt.Printf("usage prompt=%v completion=%v total=%v\n",
        usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"])
}

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:

elapsed_ms 6436
id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv
model gpt-4o-mini
content ADC_GO_SDK_OK
usage prompt=16 completion=5 total=21

The id, elapsed_ms, and usage in the responses of the three languages come from the same source: authenticated by PlatformGateway → upstream OpenAI compatible service → written into 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