@acedatacloud/sdk è l’SDK ufficiale TypeScript / JavaScript di Ace Data Cloud, che incapsula tutti i servizi su api.acedata.cloud in metodi tipizzati come client.openai.chat.completions.create(...), client.images.generate(...), client.search.google(...), ecc., con supporto per flussi SSE, retry backoff e eccezioni tipizzate.
Può essere utilizzato in Node.js, Deno, Bun e nei moderni browser (con bundler).
Indirizzi del codice sorgente e del pacchetto:
- Repository SDK: https://github.com/AceDataCloud/SDK
- npm SDK: https://www.npmjs.com/package/@acedatacloud/sdk
Installazione
- La versione del pacchetto è
2026.504.2(CalVer, 2° aggiornamento della 504ª settimana ISO del 2026). AceDataCloudè la classe principale utilizzata per costruire il client, accessibile dall’esportazione predefinita.
Preparare il Token API
Fare riferimento a Panoramica SDK - Richiesta Token API per ottenere il token, quindi in shellexport:
apiToken, l’SDK leggerà automaticamente la variabile d’ambiente ACEDATACLOUD_API_TOKEN. Se nel tuo ambiente è già presente ACEDATACLOUD_API_KEY (convenzione del repository del progetto), puoi passarlo esplicitamente: new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }).
Esempio 1: chat.completions (non in streaming)
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQAè l’ID della risposta compatibile con OpenAI, che può essere cercato nel registro delle attività della console.content ADC_TS_SDK_OKè l’identificativo fisso restituito dal modello, che dimostra che la risposta non è stata alterata dall’SDK.- Una chat completion consuma circa 22 token, addebitati secondo il prezzo di gpt-4o-mini.
- L’SDK dichiara la risposta come
Record<string, unknown>, a runtime è un oggetto JSON, l’accesso tramite punti come.id/.choices[0].message.contentfunziona in.mjs, Node REPL, Bun; in progetti TypeScript rigorosi potrebbe essere necessario(res as any).ido disabilitarenoImplicitAnyin tsconfig.
Esempio 2: chat.completions (streaming SSE)
Attivandostream: true, create restituisce un iteratore asincrono, ogni frame è un ChatCompletionChunk.
- Il ritardo del primo frame di 2481 ms è il tempo impiegato dal modello per generare il primo token; i successivi 12 frame sono arrivati tutti entro 135 ms.
- I 13 frame insieme formano
"1 2 3 4 5", ogni token è un frame separato + l’ultimo frame confinish_reason. - Lo streaming non consuma più token rispetto al non streaming, ma il ritardo del primo token è significativamente ridotto, adatto per interfacce utente in tempo reale.
Esempio 3: images.generate (NanoBanana)
client.images.generate({ provider: 'nano-banana', ... }) restituisce direttamente in modo sincrono, non è necessario passare il parametro wait — l’API di NanoBanana genera già in modo sincrono.
image_urlè un indirizzo stabile su CDN, può essere utilizzato direttamente in<img src />o per il download.- La maggior parte del tempo di 16,6 secondi è dedicata all’inferenza del modello, il costo dell’SDK locale è trascurabile.
trace_idè l’ID della richiesta assegnato dalla piattaforma, se ci sono problemi, fornire questo ID al supporto clienti può aiutare a localizzare rapidamente il problema.- Per i servizi di tipo asincrono (Midjourney, Sora, Veo, ecc.) è necessario il polling di TaskHandle, vedere Polling dei task SDK e risposte in streaming.
Esempio 4: gestione degli errori tipizzata
L’SDK genera errori come sottoclassi specifiche in base allo stato HTTP (AuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError ecc.); è possibile usare instanceof per effettuare ramificazioni precise.
- Il codice 401 viene mappato automaticamente a
AuthenticationError; il codice applicativo può usareinstanceofper effettuare ramificazioni precise. code: invalid_tokenindica che l’API Key non è valida; controlla le credenziali.- Analogamente, 429 →
RateLimitError, 400 →BadRequestError, 5xx →InternalServerError.
Esempio 5: routing multi-modello
Lo stesso client può passare liberamente da un servizio all’altro; è sufficiente che il nome del modello sia lo stesso.- Un unico codice e un unico token per coprire quattro tipi di servizi di modelli: OpenAI / Google / DeepSeek / xAI.
gemini-2.5-flashquesta volta non ha restituitoADC_OK: si tratta di una differenza nello stile di output del modello. L’SDK non ha omesso silenziosamente nulla e ha inoltrato fedelmente all’applicazione le parole originali del modello.- Il costo viene calcolato in base al prezzo per token di ciascun modello.
Esempio 6: Ricerca Google
- Una richiesta ha restituito 10 risultati organici, il nome del campo è
organic(nonorganic_results). - La ricerca è stata effettuata tramite il servizio Serp, con addebito per ogni richiesta.
- Lo stesso client può sia chattare che cercare, un solo token è sufficiente.
Opzioni di configurazione
Utilizzo nel browser
@acedatacloud/sdk è un pacchetto ESM + ISO (isomorfico), può essere importato direttamente in browser moderni con bundler. Nota: non codificare in modo rigido il token API nel codice front-end. Raccomandato per il front-end:
- Utilizzare X402
paymentHandler— il portafoglio utente paga in USDC per richiesta, senza necessità di token. - Oppure utilizzare l’SDK sul proprio server, il browser chiama solo il proprio backend.
Avanzato: Polling delle attività e risposta in streaming
- Servizi di tipo attività (Midjourney, Sora, Veo, Suno): utilizzare
TaskHandleper il polling, dettagli su unità, timeout e ripetizioni possono essere trovati in SDK Polling delle attività e Streaming. - Chat in streaming: l’esempio 2 di questa pagina è già stato dimostrato; audio / video in streaming sono supportati allo stesso modo.
Avanzato: Hook di pagamento X402
Se non si desidera richiedere un token API e si desidera pagare per richiesta sulla blockchain, è possibile utilizzarepaymentHandler:
createX402PaymentHandleraccetta nel lato TypeScript{ network, evmProvider, evmAddress, preferScheme? }(EVM chain) o{ network: 'solana', solanaWallet }(Solana). Se il server Node non hawindow.ethereum, utilizzareviem’screateWalletClient(basato su chiave privata) per incapsulare un provider compatibile con EIP-1193 da passare; dettagli e risultati reali sulla blockchain possono essere trovati in SDK + Hook di pagamento X402.

