@acedatacloud/sdk is the official TypeScript / JavaScript SDK for Ace Data Cloud, encapsulating all services on api.acedata.cloud into typed methods such as client.openai.chat.completions.create(...), client.images.generate(...), client.search.google(...), etc., with built-in SSE streaming, retry backoff, and typed exceptions.
It can be used in Node.js, Deno, Bun, and modern browsers (with bundler).
Source code and package address:
- SDK repository: https://github.com/AceDataCloud/SDK
- npm SDK: https://www.npmjs.com/package/@acedatacloud/sdk
Installation
- The package version is
2026.504.2(CalVer, the 2nd revision of the 504th ISO week of 2026). AceDataCloudis the main class used to construct the client, accessible from the default export.
Prepare API Token
Refer to SDK Overview - Apply for API Token to obtain the token, thenexport it in the shell:
apiToken is not passed, the SDK will automatically read the ACEDATACLOUD_API_TOKEN environment variable. If you already have ACEDATACLOUD_API_KEY stored in your environment (as per project repository convention), you can explicitly pass it: new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }).
Example 1: chat.completions (non-streaming)
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQAis the OpenAI compatible response ID, which can be found in the console usage history.content ADC_TS_SDK_OKis the fixed identifier returned by the model, proving that the response has not been tampered with by the SDK.- One chat completion consumes about 22 tokens, billed at the rate of gpt-4o-mini.
- The SDK declares the response as
Record<string, unknown>, which is a JSON object at runtime; dot access like.id/.choices[0].message.contentcan run under.mjs, Node REPL, and Bun; strict TypeScript projects may require(res as any).idor turning offnoImplicitAnyin tsconfig.
Example 2: chat.completions (SSE streaming)
By enablingstream: true, create returns an asynchronous iterator, with each frame being a ChatCompletionChunk.
- The first frame delay of 2481 ms is the time taken by the model to generate the first token; the subsequent 12 frames arrived within 135 ms.
- The 13 frames together form
"1 2 3 4 5", with each token forming a separate frame + the last frame containingfinish_reason. - Streaming does not save more tokens than non-streaming, but the first token delay is significantly reduced, making it suitable for real-time UI.
Example 3: images.generate (NanoBanana)
client.images.generate({ provider: 'nano-banana', ... }) returns directly synchronously, no need to pass the wait parameter—the NanoBanana API itself generates synchronously.
image_urlis a stable address on the CDN, which can be directly used in<img src />or downloaded.- Most of the 16.6 seconds is spent on model inference, with local SDK overhead being negligible.
trace_idis the request ID assigned by the platform; if issues arise, providing this ID to customer service can help locate the problem quickly.- For asynchronous services (Midjourney, Sora, Veo, etc.), TaskHandle polling is required; see SDK Task Polling and Streaming Responses.
Example 4: Typed error handling
The SDK throws errors as specific subclasses based on the HTTP status (AuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError, etc.), allowing precise branching with instanceof.
- 401 is automatically mapped to
AuthenticationError, and application code can useinstanceoffor precise branching. code: invalid_tokenindicates that the API key is invalid. Please check your credentials.- Likewise, 429 →
RateLimitError, 400 →BadRequestError, and 5xx →InternalServerError.
Example 5: Multi-model routing
The same client can switch freely between multiple services, as long as the model name is the same.- One codebase and one token, covering four model service providers: OpenAI / Google / DeepSeek / xAI.
gemini-2.5-flashdid not returnADC_OKthis time. This is a difference in the model’s own output style—the SDK did not silently discard anything and faithfully forwarded the model’s original response to the application.- Pricing is based on each model’s per-token rate.
Example 6: Google Search
- One request retrieves 10 organic results, with the field name
organic(notorganic_results). - The search goes through the Serp service, billed per request.
- The same client instance can both chat and search, one token is sufficient.
Configuration Options
Browser Usage
@acedatacloud/sdk is an ESM + ISO (universal) package that can be directly imported in modern browsers with bundlers. Note: Do not hard-code the API Token in frontend code. Recommended for frontend:
- Use X402
paymentHandler— user wallets pay per use in USDC, no token required. - Or use the SDK on your own server, with the browser only calling your own backend.
Advanced: Task Polling and Streaming Responses
- Task-based services (Midjourney, Sora, Veo, Suno): use
TaskHandlefor polling, unit, timeout, and retry details see SDK Task Polling and Streaming. - Streaming chat: already demonstrated in Example 2; streaming audio/video is also supported.
Advanced: X402 Payment Hooks
If you do not want to apply for an API Token and want to pay per use on-chain, you can usepaymentHandler:
createX402PaymentHandleraccepts{ network, evmProvider, evmAddress, preferScheme? }(EVM chain) or{ network: 'solana', solanaWallet }(Solana) on the TypeScript side. When the Node server does not havewindow.ethereum, please useviem’screateWalletClient(based on private key) to wrap an EIP-1193 compatible provider and pass it in; detailed methods and real on-chain results see SDK + X402 Payment Hooks.

