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

> Platform API guide - Ace Data Cloud

Ace Data Cloud предоставляет официальные клиентские SDK на языках TypeScript / Python / Go, которые оборачивают возможности chat completions, images, video, music, search, x402 и другие на `api.acedata.cloud` в методы с сильной типизацией, избавляя от необходимости вручную писать HTTP, SSE, опрос задач, обработку ошибок и работу с повторными попытками.

Эта глава организована в порядке реального подключения: сначала получите API Token в консоли, затем выберите язык и посмотрите соответствующий раздел, а затем ознакомьтесь с продвинутыми методами опроса задач, потоковых ответов и X402 для оплаты на блокчейне.

## Репозиторий и пакеты

* Исходный код SDK (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 клиент (TypeScript): [`@acedatacloud/x402-client`](https://www.npmjs.com/package/@acedatacloud/x402-client)
* X402 клиент (Python): [`acedatacloud-x402`](https://pypi.org/project/acedatacloud-x402/)

## Матрица возможностей на трех языках

| Возможность | TypeScript | Python | Go |
| - | - | - | - |
| `chat.completions.create` (непотоковый) | ✅ | ✅ | ✅ |
| `chat.completions.create` (потоковый SSE) | ✅ | ✅ | ✅ |
| `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 | ✅ (миллисекунды) | ✅ (секунды) | 🚧 |
| Асинхронный клиент | ✅ (Promise) | ✅ (`AsyncAceDataCloud`) | ✅ (`context.Context`) |
| Автоматические повторные попытки + экспоненциальная задержка | ✅ | ✅ | ✅ |
| Типизированные исключения (`AuthenticationError` / `RateLimitError` …) | ✅ | ✅ | ✅ |
| X402 `paymentHandler` хук (оплата на блокчейне без токена) | ✅ | ✅ | ❌ (в планах) |

> Мультимедийные ресурсы и опрос задач Go SDK в настоящее время находятся на стадии alpha (псевдовариант `v0.0.0-20260505072132-4a3d921f9bb4`), стабильная возможность — это `chat.completions`. Для мультимедийных сценариев рекомендуется использовать TypeScript или Python.

## Когда использовать SDK / MCP / нативный HTTP / X402

| Сцена | Рекомендуемый способ |
| - | - |
| Серверы на стороне бэкенда, CLI, автоматизированные скрипты, фреймы Agent | **SDK** (в этой главе) |
| Вызовы клиентов MCP, таких как Claude Desktop / Cursor / Cline | MCP Servers |
| Одноразовая проверка curl, отладка, встроенные среды, поддерживающие только HTTP | Нативный HTTP (быстрый старт для каждого сервиса) |
| Не хотите создавать API Token, хотите платить USDC по цепочке вызовов | [Руководство по интеграции X402](https://platform.acedata.cloud/documents/x402-integration) |

SDK и X402 не исключают друг друга: SDK поддерживает как «путь токена», так и «путь `paymentHandler`», подробнее см. [SDK + X402 платежный хук](https://platform.acedata.cloud/documents/sdk-x402-payment).

## Запрос API Token

Чтобы использовать SDK, сначала получите API Token в [консоли Ace Data Cloud - Список приложений](https://platform.acedata.cloud/console/applications):

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

Если вы еще не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, чтобы пригласить вас зарегистрироваться и войти. После входа или регистрации вы будете автоматически возвращены на текущую страницу.

При первом запросе будет предоставлен бесплатный лимит, чтобы вы могли бесплатно опробовать различные AI-сервисы, предлагаемые Ace Data Cloud.

Скопируйте только что полученный токен, далее будем обозначать его как `{token}`.

## Унифицированные переменные окружения

SDK на трех языках автоматически считывает одну и ту же переменную окружения `ACEDATACLOUD_API_TOKEN`, рекомендуется использовать `export` в shell, чтобы SDK автоматически подхватывал:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN={token}
# Опционально: по умолчанию https://api.acedata.cloud
# export ACEDATACLOUD_BASE_URL=https://api.acedata.cloud
```

Также можно явно передать при создании клиента, соответствующие имена параметров для трех языков:

* 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`. Каждый фрагмент содержит **реальный результат выполнения**, вы можете воспроизвести его с вашим собственным токеном.

### 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));
```

> SDK в настоящее время объявляет ответ как `Record<string, unknown>`, во время выполнения это обычный JSON-объект, к которому можно обращаться по полям. В строгих проектах TS, если возникают ошибки типов, можно временно использовать `as any`, или обратиться к [SDK опросу задач и потоковым ответам](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) для создания пользовательской обертки с типами.

Результат выполнения программы:

```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": "Ответьте точно: 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")}))
```

> Python SDK текущий возвращает `dict`, поэтому используйте `res["id"]`, а не `res.id`. Это отличается от `openai-python`, на это нужно обратить внимание при миграции.

Результат выполнения программы:

```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": "Ответьте точно: 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"])
}
```

> Go SDK ответ единообразно представляет как `map[string]any`, нет строгих типов struct, требуется самостоятельно выполнять приведение типов. Все ресурсы доступны через цепочку методов: `client.OpenAI().Chat().Completions().Create(...)`.

Результат выполнения программы:

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

Ответы на трех языках `id`, `elapsed_ms`, `usage` происходят из одного источника: через PlatformGateway аутентификация → целевой OpenAI совместимый API → запись в учетные записи. Поле `content` является реальным выводом модели, использование фиксированного идентификатора `ADC_*_OK` предназначено для подтверждения, что ответ не был изменен SDK.

## Рекомендуемый порядок чтения

1. [Руководство по интеграции SDK TypeScript](https://platform.acedata.cloud/documents/sdk-typescript) — код, который можно запустить после `npm install`.
2. [Руководство по интеграции SDK Python](https://platform.acedata.cloud/documents/sdk-python) — три набора методов: синхронный, асинхронный, потоковый.
3. [Руководство по интеграции SDK Go](https://platform.acedata.cloud/documents/sdk-go) — стиль Go с `context.Context` и потоками канала.
4. [SDK опрос задач и потоковые ответы](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) — различия в единицах TaskHandle, детали реализации SSE, повторные попытки с экспоненциальной задержкой.
5. [SDK + X402 платежные хуки](https://platform.acedata.cloud/documents/sdk-x402-payment) — без токена, расчет по вызову на блокчейне.

## Как проверить оставшийся лимит

Через [консоль Ace Data Cloud - Список приложений](https://platform.acedata.cloud/console/applications) можно просмотреть текущий остаток на счете.

Через [консоль Ace Data Cloud - История использования](https://platform.acedata.cloud/console/usages) можно просмотреть всю историю использования и детали списания.

## Узнать больше

* 📦 [Исходный код SDK monorepo](https://github.com/AceDataCloud/SDK)
* 🔌 [Руководство по интеграции X402](https://platform.acedata.cloud/documents/x402-integration)
* 🛠 Учебник по серверам MCP
* 📊 [Список услуг и цены](https://platform.acedata.cloud/services)


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