> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Ace Data Cloud SDK Overview

> Platform integration guide - Ace Data Cloud

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

* SDK Source Code (monorepo): [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* TypeScript: [`@acedatacloud/sdk`](https://www.npmjs.com/package/@acedatacloud/sdk)
* Python: [`acedatacloud`](https://pypi.org/project/acedatacloud/)
* Go: [`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)
* X402 Client (TypeScript): [`@acedatacloud/x402-client`](https://www.npmjs.com/package/@acedatacloud/x402-client)
* X402 Client (Python): [`acedatacloud-x402`](https://pypi.org/project/acedatacloud-x402/)

## 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 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

| 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, 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](https://platform.acedata.cloud/documents/x402-integration) |

SDK and X402 are not mutually exclusive: the SDK supports both "token path" and "`paymentHandler` path", see [SDK + X402 Payment Hook](https://platform.acedata.cloud/documents/sdk-x402-payment).

## Applying for API Token

To use the SDK, first apply for an API Token at [Ace Data Cloud Console - Application List](https://platform.acedata.cloud/console/applications):

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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:

```bash theme={null}
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 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

```ts theme={null}
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](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) to create a custom typed wrapper.

Program running result:

```text theme={null}
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

```python theme={null}
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:

```text theme={null}
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

```go theme={null}
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:

```text theme={null}
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 → 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.

## Recommended Reading Order

1. [TypeScript SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-typescript) —— Code that can run after `npm install`.
2. [Python SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-python) —— Three sets of usage: synchronous, asynchronous, and streaming.
3. [Go SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-go) —— Go style `context.Context` and channel streaming.
4. [SDK Task Polling and Streaming Response](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) —— Differences in TaskHandle units, SSE implementation details, and retry backoff.
5. [SDK + X402 Payment Hook](https://platform.acedata.cloud/documents/sdk-x402-payment) —— 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](https://platform.acedata.cloud/console/applications).

You can view all usage history and billing details through the [Ace Data Cloud Console - Usage History](https://platform.acedata.cloud/console/usages).

## Learn More

* 📦 [SDK monorepo source code](https://github.com/AceDataCloud/SDK)
* 🔌 [X402 Integration Guide](https://platform.acedata.cloud/documents/x402-integration)
* 🛠 MCP Servers Tutorial
* 📊 [Service List and Pricing](https://platform.acedata.cloud/services)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.