Passer au contenu principal
@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 :

Installation

Si vous avez besoin de payer sur la chaîne X402 (sans chemin API Token), installez-en un autre :
Sortie de vérification de version d’un projet npm propre :
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 :
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)

Résultat de l’exécution du programme :
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.
Résultat de l’exécution du programme :
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.
Résultat de l’exécution du programme :
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 typée des erreurs

Le SDK lève des erreurs sous forme de sous-classes spécifiques selon le statut HTTP (AuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError, etc.) ; vous pouvez utiliser instanceof pour effectuer des branchements précis.
Résultat de l’exécution du programme :
Explication du résultat :
  • Le code 401 est automatiquement mappé vers AuthenticationError ; le code métier peut utiliser instanceof pour effectuer des branchements précis.
  • code: invalid_token indique que la clé API n’est pas valide ; veuillez vérifier vos identifiants.
  • De même, 429 → RateLimitError, 400 → BadRequestError et 5xx → InternalServerError.

Exemple 5 : routage multi-modèles

Un même client peut basculer librement entre plusieurs services, à condition que le nom du modèle soit identique.
Résultat de l’exécution du programme :
Explication du résultat :
  • Une base de code, un token, pour couvrir quatre types de services de modèles : OpenAI / Google / DeepSeek / xAI.
  • Cette fois, gemini-2.5-flash n’a pas renvoyé ADC_OK ; il s’agit d’une différence dans le style de sortie du modèle. Le SDK n’a rien supprimé silencieusement et a fidèlement transmis les propos du modèle à l’application.
  • La tarification est calculée selon le prix unitaire par token de chaque modèle.

Exemple 6 : Recherche Google

Résultat du programme :
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

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 :
  1. Utiliser X402 paymentHandler — le portefeuille utilisateur signe USDC à la demande, sans besoin de token.
  2. 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 :
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.

En savoir plus