Tutoriel d'intégration du SDK TypeScript

@acedatacloud/sdk est le SDK TypeScript / JavaScript officiel d’Ace Data Cloud, qui encapsule tous les services sur api.acedata.cloud en méthodes typées telles que client.openai.chat.completions.create(...), client.images.generate(...), client.search.google(...), etc., avec un flux SSE intégré, une stratégie de réessai avec backoff et des exceptions typées. Il peut être utilisé dans Node.js, Deno, Bun et les navigateurs modernes (avec bundler). Adresse du code source et du package :

Dépôt SDK : https://github.com/AceDataCloud/SDK
npm SDK : https://www.npmjs.com/package/@acedatacloud/sdk

Installation

npm install @acedatacloud/sdk
# ou pnpm add / yarn add / bun add

Si vous avez besoin de payer sur la chaîne X402 (sans chemin API Token), installez-en un autre :

npm install @acedatacloud/x402-client ethers

Sortie de vérification de version d’un projet npm propre :

$ npm ls @acedatacloud/sdk
└── @acedatacloud/sdk@2026.504.2

$ node -e "console.log(require('@acedatacloud/sdk').AceDataCloud?.name)"
AceDataCloud

Explication des résultats :

La version du package est 2026.504.2 (CalVer, 2ème révision de la 504ème semaine ISO de l’année 2026).
AceDataCloud est la classe principale utilisée pour construire le client, accessible depuis l’exportation par défaut.

Préparer le Token API

Référez-vous à Aperçu du SDK - Demander un Token API pour obtenir le token, puis dans le shell export :

export ACEDATACLOUD_API_TOKEN={token}

Lors de la construction du client, ne passez pas apiToken, le SDK lira automatiquement la variable d’environnement ACEDATACLOUD_API_TOKEN. Si votre environnement contient déjà ACEDATACLOUD_API_KEY (convention du dépôt de projet), vous pouvez le passer explicitement : new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }).

Exemple 1 : chat.completions (non stream)

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

const client = new AceDataCloud();

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

Résultat de l’exécution du programme :

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}

Explication des résultats :

id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQA est l’ID de réponse compatible avec OpenAI, que vous pouvez retrouver dans l’historique utilisation du tableau de bord.
content ADC_TS_SDK_OK est l’identifiant fixe réellement retourné par le modèle, prouvant que la réponse n’a pas été altérée par le SDK.
Une complétion de chat consomme environ 22 tokens, facturée au tarif unitaire de gpt-4o-mini.
Le SDK déclare la réponse comme Record<string, unknown>, à l’exécution c’est un objet JSON, l’accès par point comme .id / .choices[0].message.content fonctionne sous .mjs, Node REPL, Bun ; dans un projet TypeScript strict, il peut être nécessaire d’utiliser (res as any).id ou de désactiver noImplicitAny dans tsconfig.

Exemple 2 : chat.completions (stream SSE)

En activant stream: true, create retourne un itérateur asynchrone, chaque trame étant un ChatCompletionChunk.

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

const client = new AceDataCloud();

const t0 = Date.now();
let firstChunkMs: number | null = null;
let chunks = 0;
const collected: string[] = [];

const stream = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: 'Count from 1 to 5, separated by single spaces, no extra text.' }
  ],
  max_tokens: 20,
  stream: true
});

for await (const chunk of stream) {
  if (firstChunkMs === null) firstChunkMs = Date.now() - t0;
  chunks++;
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) collected.push(delta);
}

console.log('total_elapsed_ms', Date.now() - t0);
console.log('first_chunk_ms', firstChunkMs);
console.log('chunks', chunks);
console.log('collected', collected.join('').trim());

Résultat de l’exécution du programme :

total_elapsed_ms 2616
first_chunk_ms 2481
chunks 13
collected 1 2 3 4 5

Explication des résultats :

Le délai de la première trame de 2481 ms est le temps pris par le modèle pour générer le premier token ; les 12 trames suivantes sont toutes arrivées en moins de 135 ms.
Les 13 trames combinées forment "1 2 3 4 5", chaque token étant dans une trame séparée + la dernière trame contenant finish_reason.
Le streaming ne consomme pas moins de tokens que le mode non stream, mais le délai du premier mot est considérablement réduit, ce qui est adapté pour une interface utilisateur en temps réel.

Exemple 3 : images.generate (NanoBanana)

client.images.generate({ provider: 'nano-banana', ... }) retourne directement de manière synchrone, pas besoin de passer le paramètre wait — l’API NanoBanana génère en synchronisation.

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

const client = new AceDataCloud();

const t0 = Date.now();
const img = await client.images.generate({
  provider: 'nano-banana',
  prompt: 'A minimalist logo of a yellow banana on a white background, flat design'
});
console.log('elapsed_ms', Date.now() - t0);
console.log('task_id', img.task_id);
console.log('trace_id', img.trace_id);
console.log('image_url', img.data[0].image_url);

Résultat de l’exécution du programme :

elapsed_ms 16634
task_id 8e4b44a6-5ece-46a4-9013-9e0c8aca2217
trace_id 9529e241-54fe-40da-98a2-871e14989fb5
image_url https://platform.cdn.acedata.cloud/nanobanana/331be1d3-3330-4196-bd1c-aa75717c549c.png

Explication des résultats :

image_url est une adresse stable sur le CDN, que vous pouvez directement utiliser dans <img src /> ou télécharger.
La majorité des 16,6 secondes est consacrée à l’inférence du modèle, les coûts du SDK local étant négligeables.
trace_id est l’ID de requête attribué par la plateforme, si un problème survient, fournir cet ID au support client peut aider à localiser rapidement le problème.
Pour les services asynchrones (Midjourney, Sora, Veo, etc.), un polling de TaskHandle est nécessaire, voir Polling de tâches SDK et réponses en streaming.

Exemple 4 : Gestion des erreurs typées

Le SDK lancera des erreurs sous forme de sous-classes spécifiques ( AuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError, etc.) en fonction de l’état HTTP, vous pouvez utiliser instanceof pour des branches précises.

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

const bad = new AceDataCloud({ apiToken: 'définitivement-pas-un-vrai-token' });

try {
  await bad.openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'salut' }],
    max_tokens: 5
  });
} catch (err: any) {
  console.log('err_class', err.constructor.name);
  console.log('status', err.statusCode);
  console.log('code', err.code);
  console.log('instanceof AuthenticationError =', err instanceof AuthenticationError);
}

Résultat du programme :

A. err_class AuthenticationError
A. status 401
A. code invalid_token
A. instanceof AuthenticationError = true

Explication des résultats :

401 est automatiquement mappé à AuthenticationError, le code métier peut utiliser instanceof pour des branches précises.
code: invalid_token provient de PlatformGateway, facilitant la comparaison avec les journaux backend.
De même 429 → RateLimitError, 400 → BadRequestError, 5xx → InternalServerError.

Exemple 5 : Routage multi-modèles

Un même client peut passer librement entre plusieurs services, tant que le nom du modèle est identique.

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

const client = new AceDataCloud();

const MODELS = ['gpt-4o-mini', 'gemini-2.5-flash', 'deepseek-v3', 'grok-3-fast'];

for (const model of MODELS) {
  const t0 = Date.now();
  try {
    const r = await client.openai.chat.completions.create({
      model,
      messages: [{ role: 'user', content: 'Répondre exactement : ADC_OK' }],
      max_tokens: 5
    });
    console.log(model.padEnd(28), `${Date.now() - t0}ms`, `content="${r.choices[0].message.content}"`);
  } catch (err: any) {
    console.log(model.padEnd(28), `${Date.now() - t0}ms`, 'ERR', err.statusCode, err.code);
  }
}

Résultat du programme :

gpt-4o-mini                  2189ms   content="ADC_OK"
gemini-2.5-flash             2569ms   content=""
deepseek-v3                  2047ms   content="ADC_OK"
grok-3-fast                  3598ms   content="ADC_OK"

Explication des résultats :

Un code, un token, couvrant les services de modèles OpenAI / Google / DeepSeek / xAI.
gemini-2.5-flash n’a pas retourné ADC_OK cette fois, en raison des différences de style de sortie du modèle - le SDK n’a pas silencieusement absorbé quoi que ce soit, transmettant fidèlement les mots du modèle au code métier.
Les prix sont facturés selon le prix unitaire réel de chaque token, le chemin ne passe qu’une seule fois par PlatformGateway.

Exemple 6 : Recherche Google

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

const client = new AceDataCloud();

const t0 = Date.now();
const r = await client.search.google({
  query: 'Ace Data Cloud',
  resource: 'web'
});
const items = (r as any).organic ?? [];
console.log('elapsed_ms', Date.now() - t0);
console.log('organic_count', items.length);
items.slice(0, 2).forEach((it: any, i: number) => {
  console.log(`#${i + 1}`, it.title, '->', it.link);
});

Résultat du programme :

elapsed_ms 2382
organic_count 10
#1 Ace Data Cloud -> https://platform.acedata.cloud/
#2 Ace Data Cloud - GitHub -> https://github.com/acedatacloud

Explication des résultats :

Une seule requête a obtenu 10 résultats organiques, le nom du champ est organic (pas organic_results).
La recherche passe par le service Serp, facturé à la demande.
Une même instance de client peut à la fois chatter et rechercher, un seul token suffit.

Options de configuration

const client = new AceDataCloud({
  // Obligatoire : token explicite ou variable d'environnement ACEDATACLOUD_API_TOKEN
  apiToken: process.env.MY_TOKEN,

  // URL de base de l'API de la plateforme, par défaut https://api.acedata.cloud
  baseURL: 'https://api.acedata.cloud',

  // Certains services (comme les métadonnées du tableau de bord) passent par le domaine de la plateforme
  platformBaseURL: 'https://platform.acedata.cloud',

  // Délai d'attente pour une seule requête, en millisecondes ; par défaut 300_000 (5 minutes)
  timeout: 300_000,

  // Nombre de tentatives de réessai automatiques, par défaut 2 ; conditions de réessai : 408 / 409 / 429 / 5xx / erreurs réseau
  maxRetries: 2,

  // En-têtes de requête personnalisés
  defaultHeaders: { 'x-app': 'my-service/1.0' }
});

Utilisation dans le navigateur

@acedatacloud/sdk est un package ESM + ISO (isomorphe), pouvant être directement importé dans des navigateurs modernes avec bundler. Attention : ne pas coder en dur le token API dans le code frontend. Recommandations pour le frontend :

Utiliser X402 paymentHandler — le portefeuille utilisateur signe USDC à la demande, sans besoin de token.
Ou utiliser le SDK sur votre propre serveur, le navigateur n’appelant que votre backend.

Avancé : Polling de tâches et réponses en streaming

Services de type tâche (Midjourney, Sora, Veo, Suno) : utiliser TaskHandle pour le polling, les détails d’unité, de délai d’attente et de réessai se trouvent dans SDK Polling de tâches et Streaming.
Chat en streaming : l’exemple 2 de cette page a déjà été démontré ; l’audio / vidéo en streaming est également pris en charge.

Avancé : Hooks de paiement X402

Si vous ne souhaitez pas demander de token API et préférez payer à la demande sur la chaîne, vous pouvez utiliser paymentHandler :

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

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider: (window as any).ethereum,  // fournisseur EIP-1193, ou viem walletClient
    evmAddress: userAddress
  })
});

createX402PaymentHandler accepte côté TypeScript { network, evmProvider, evmAddress, preferScheme? } (chaîne EVM) ou { network: 'solana', solanaWallet } (Solana). Si le serveur Node n’a pas window.ethereum, utilisez viem’s createWalletClient (basé sur la clé privée) pour encapsuler un fournisseur compatible EIP-1193 à transmettre ; les détails et les résultats réels sur la chaîne se trouvent dans SDK + Hooks de paiement X402.

Comment vérifier le solde restant

Via Console Ace Data Cloud - Liste des applications, vous pouvez vérifier le solde restant de votre compte. Via Console Ace Data Cloud - Historique d’utilisation, vous pouvez consulter tout l’historique d’utilisation et les détails de facturation.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Tutoriel d'intégration du SDK TypeScript

Installation

Préparer le Token API

Exemple 1 : chat.completions (non stream)

Exemple 2 : chat.completions (stream SSE)

Exemple 3 : images.generate (NanoBanana)

Exemple 4 : Gestion des erreurs typées

Exemple 5 : Routage multi-modèles

Exemple 6 : Recherche Google

Options de configuration

Utilisation dans le navigateur

Avancé : Polling de tâches et réponses en streaming

Avancé : Hooks de paiement X402

Comment vérifier le solde restant

En savoir plus

​Installation

​Préparer le Token API

​Exemple 1 : chat.completions (non stream)

​Exemple 2 : chat.completions (stream SSE)

​Exemple 3 : images.generate (NanoBanana)

​Exemple 4 : Gestion des erreurs typées

​Exemple 5 : Routage multi-modèles

​Exemple 6 : Recherche Google

​Options de configuration

​Utilisation dans le navigateur

​Avancé : Polling de tâches et réponses en streaming

​Avancé : Hooks de paiement X402

​Comment vérifier le solde restant

​En savoir plus

Installation

Préparer le Token API

Exemple 1 : chat.completions (non stream)

Exemple 2 : chat.completions (stream SSE)

Exemple 3 : images.generate (NanoBanana)

Exemple 4 : Gestion des erreurs typées

Exemple 5 : Routage multi-modèles

Exemple 6 : Recherche Google

Options de configuration

Utilisation dans le navigateur

Avancé : Polling de tâches et réponses en streaming

Avancé : Hooks de paiement X402

Comment vérifier le solde restant

En savoir plus