> ## 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, спочатку перейдіть до [консолі Ace Data Cloud - Список додатків](https://platform.acedata.cloud/console/applications) та отримайте API Token:

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

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

При першому запиті вам буде надано безкоштовний ліміт, щоб ви могли безкоштовно випробувати різні AI послуги, які надає Ace Data Cloud.

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

## Уніфіковані змінні середовища

SDK трьох мов автоматично зчитує одну й ту ж змінну середовища `ACEDATACLOUD_API_TOKEN`, рекомендується в shell виконати `export`, щоб 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": "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")}))
```

> 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": "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"])
}
```

> Go SDK відповіді завжди є `map[string]any`, немає сильно типізованих структур, потрібно самостійно виконувати приведення типів. Всі ресурси доступні через ланцюг методів: `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. [TypeScript SDK інтеграційний посібник](https://platform.acedata.cloud/documents/sdk-typescript) — код, який можна запустити після `npm install`.
2. [Python SDK інтеграційний посібник](https://platform.acedata.cloud/documents/sdk-python) — три набори використання: синхронне, асинхронне, потокове.
3. [Go SDK інтеграційний посібник](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 Servers
* 📊 [Список послуг та ціни](https://platform.acedata.cloud/services)


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