AceDataCloud TypeScript SDK

Official TypeScript/Node.js client for the AceDataCloud API.

Requires Node.js 18+ (uses native fetch).

Get your Ace Data Cloud API key

1. Open Ace Data Cloud → Applications. Sign in, or register an account first.
2. Find General application. If it has not been created, choose Initialize General Application. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and current pricing.
3. Copy the API Key from the application card, or open Keys / Manage Keys → Create to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
4. When creating a key, review Expiration Time, Set Usage Limitation, and Allowed APIs. Enable only the restrictions you need, allow the operations you will call, then click Create and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
5. Copy only the token value, without quotation marks, spaces, or Bearer . An API Key / API Token field expects this raw value; only a manually configured HTTP Authorization header needs the Bearer prefix. A platform-... account-management token cannot replace a generation API key.

Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.

Use this application key for API requests. SDK account-management methods require the separate credential described in their management documentation; do not interchange it with the API key. The optional x402 payment flow below is a separate way to pay for supported requests.

Installation

npm install @acedatacloud/sdk

Quick Start

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

const client = new AceDataCloud({ apiToken: 'your-token' });

// OpenAI-compatible chat completions
const response = await client.openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

Streaming

const stream = await client.openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? '');
}

Resources

| Resource | Description | |----------|-------------| | client.openai | OpenAI-compatible chat completions and responses | | client.chat | Native chat messages | | client.images | Image generation (Flux, Seedream, Nano Banana, etc.) | | client.audio | Music generation (Suno) | | client.video | Video generation (Luma, Sora, Veo, etc.) | | client.search | Web search (Google SERP) | | client.face | Face analysis & transformation (swap, beautify, age, cartoon) | | client.shorturl | Short URL creation | | client.tasks | Cross-service async task polling | | client.files | File uploads | | client.platform | Applications, credentials, models management |

Native Claude Messages

Thinking and output configuration are passed through without SDK model-specific enum or combination checks. The selected model determines which values it accepts. For the beta display: 'updates' mode, set the required header on a dedicated client (client headers apply to every request):

const claude = new AceDataCloud({
  apiToken: 'your-token',
  headers: { 'anthropic-beta': 'thinking-display-updates-2026-08-18' },
});

const response = await claude.chat.messages.create({
  model: 'claude-sonnet-5-5',
  messages: [{ role: 'user', content: 'Explain this code.' }],
  thinking: { type: 'adaptive', display: 'updates' },
  output_config: { effort: 'high' },
});

Streaming and claude.chat.messages.countTokens(...) also preserve thinking configuration. Parameter pass-through does not guarantee model support; API errors are returned through the SDK's normal error handling.

OpenAI Embeddings

const embeddings = await client.openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'The food was delicious and the waiter...',
});

Supported models are text-embedding-3-small and text-embedding-3-large. text-embedding-ada-002 is no longer available. When migrating an existing index, regenerate its vectors and rebuild the index; do not mix old and new model vectors.

Image Generation (with Task Polling)

// Default provider (nano-banana)
const task = await client.images.generate({ prompt: 'A sunset over mountains' });
const result = await task.wait();
console.log(result.image_url);

// Use a specific provider
const fluxTask = await client.images.generate({
  prompt: 'A sunset over mountains',
  provider: 'flux',
});

Nano Banana 2.1

Select model: 'nano-banana-2.1' explicitly for generation or editing at 1K, 2K, or 4K. Omitting model still uses nano-banana; there is no nano-banana-2.1:official variant.

const task = await client.nanobanana.generate({
  action: 'generate',
  model: 'nano-banana-2.1',
  prompt: 'A blue ceramic vase on a cream background',
  resolution: '2K',
  aspectRatio: '1:1',
});
await task.wait();
const imageUrls = task.urls();

const editTask = await client.nanobanana.generate({
  action: 'edit',
  model: 'nano-banana-2.1',
  prompt: 'Change the vase to green; preserve the background',
  imageUrls,
  resolution: '4K',
});
await editTask.wait();

The public model ID also works with client.openai.images.generate(...) and client.openai.images.edit(...); those use the OpenAI-compatible fields (image for editing) and return response objects, not task handles.

Maestro Video Production

Use the provider client to request one finished video in one language:

const task = await client.maestro.generate({
  prompt: 'Explain vector databases to beginners in 20 seconds',
  langs: ['en'],
  aspect: '9:16',
  duration: 20,
  scenario: 'narrated',
});
const result = await task.wait();

langs defaults to ['zh-cn'] and must contain exactly one language; create separate tasks for other languages. The completed result contains one video in response.data.variants. To revise a video, use action: 'remix', 'edit', or 'extend' with refTaskId: task.id.

There is no quality tier: all videos use 1080p/30fps and target durations of 5–300 seconds. Successful tasks cost 0.7 Credits per actual delivered second, with integer billed seconds capped at the requested duration (falling back to that duration if it cannot be read). All scenarios, actions, and languages have the same rate; failed tasks and /maestro/tasks polling are free.

Multi-Provider Support

Image, video, and audio resources support a provider parameter to switch between services:

// Video — default is 'sora'
await client.video.generate({ prompt: 'A cat playing piano', provider: 'kling' });
await client.video.generate({ prompt: 'Ocean waves', provider: 'luma' });

// Audio — default is 'suno'
await client.audio.generate({ prompt: 'A jazz song', provider: 'producer' });

Available providers:

| Resource | Providers | |----------|-----------| | client.images | nano-banana (default), flux, seedream | | client.video | sora (default), luma, veo, kling, hailuo, seedance, wan, pika, pixverse | | client.audio | suno (default), producer, fish |

Error Handling

import { AceDataCloud, AuthenticationError, RateLimitError } from '@acedatacloud/sdk';

const client = new AceDataCloud({ apiToken: 'your-token' });
try {
  await client.search.google({ query: 'test' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid or expired token');
  } else if (err instanceof RateLimitError) {
    console.error('Too many requests');
  }
}

Configuration

const client = new AceDataCloud({
  apiToken: 'your-token',
  baseURL: 'https://x402.acedata.cloud',
  platformBaseURL: 'https://platform.acedata.cloud',
  timeout: 300000,    // ms
  maxRetries: 2,
});

The token can also be set via the ACEDATACLOUD_API_TOKEN environment variable.

Paying with X402 Instead of a Bearer Token

The SDK supports a pluggable paymentHandler that is invoked when the API returns 402 Payment Required. Combine it with @acedatacloud/x402-client to pay for requests on-chain (Base, Solana, SKALE) instead of using a Bearer token:

npm install @acedatacloud/sdk @acedatacloud/x402-client

import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const client = new AceDataCloud({
  // No apiToken needed — the x402 handler pays per request.
  paymentHandler: createX402PaymentHandler({
    network: 'base',               // or 'solana' | 'skale'
    evmProvider: window.ethereum,
    evmAddress: '0xYourAddress...',
  }),
});

const result = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
  max_tokens: 10,
});

On each API call, the SDK first sends the request unauthenticated. If the server replies with 402, the SDK passes the accepts list to the handler, which signs and returns an X-Payment header. The SDK retries the request once with that header. Everything else — task polling, streaming, retries, error mapping — keeps working exactly the same.

You can still pass a Bearer token alongside the handler if you want a mixed mode (some endpoints via subscription, others via x402) — the SDK only invokes the handler when it actually sees a 402.

License

MIT