Skip to main content
Ace Data Cloud offre SDK ufficiali per TypeScript / Python / Go, che incapsulano le capacità di chat completions, immagini, video, musica, ricerca, x402, ecc. disponibili su api.acedata.cloud in metodi fortemente tipizzati, risparmiando il lavoro di scrittura manuale di HTTP, SSE, polling dei task, gestione degli errori e backoff per i retry. Questo capitolo è organizzato secondo l’ordine di accesso reale: prima ottenere il token API nella console, poi scegliere il linguaggio e consultare il capitolo corrispondente, infine esaminare il polling dei task, le risposte in streaming e l’uso avanzato dei pagamenti sulla blockchain X402.

Repository e pacchetti

Matrice delle capacità dei tre linguaggi

Le risorse multimediali e il polling dei task del SDK Go sono attualmente in fase alpha (versione fittizia v0.0.0-20260505072132-4a3d921f9bb4), la capacità stabile è chat.completions. Per scenari multimediali, si consiglia di scegliere TypeScript o Python.

Quando utilizzare SDK / MCP / HTTP nativo / X402

SDK e X402 non si escludono a vicenda: l’SDK supporta sia il “percorso del token” che il “percorso paymentHandler”, vedi SDK + gancio di pagamento X402.

Richiesta di un token API

Per utilizzare l’SDK, prima di tutto vai su Ace Data Cloud Console - Elenco delle applicazioni per richiedere un token API: Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente. Alla prima richiesta, verrà fornito un credito gratuito, permettendoti di provare gratuitamente i vari servizi AI offerti da Ace Data Cloud. Copia il token appena ottenuto, che d’ora in poi verrà indicato come {token}.

Variabili d’ambiente unificate

Gli SDK dei tre linguaggi leggeranno automaticamente la stessa variabile d’ambiente ACEDATACLOUD_API_TOKEN, si consiglia di export nel shell, in modo che l’SDK possa raccoglierla automaticamente:
Puoi anche passarlo esplicitamente durante la costruzione del client, i nomi dei parametri corrispondenti per i tre linguaggi sono:
  • TypeScript: new AceDataCloud({ apiToken: '{token}' })
  • Python: AceDataCloud(api_token="{token}")
  • Go: adc.NewClient(adc.WithAPIToken("{token}"))
Nota: nel repository del progetto AceDataCloud è consuetudine utilizzare ACEDATACLOUD_API_KEY (in .env / CI), ma questi tre SDK riconoscono solo ACEDATACLOUD_API_TOKEN. Se nel tuo ambiente hai solo ACEDATACLOUD_API_KEY, ti preghiamo di passarlo esplicitamente durante la costruzione.

Esempi di utilizzo in 30 secondi

Le seguenti tre sezioni di codice fanno la stessa cosa: chiamano gpt-4o-mini, chiedendo di rispondere solo con ADC_*_OK. Ogni sezione include il risultato reale dell’esecuzione, che puoi riprodurre con il tuo token.

TypeScript

L’SDK attualmente dichiara la risposta come Record<string, unknown>, a runtime è un normale oggetto JSON, accessibile direttamente per campo. In progetti TS rigorosi, se si incontrano errori di tipo, è possibile utilizzare temporaneamente as any, oppure fare riferimento a Polling dei task e risposte in streaming dell’SDK per personalizzare un wrapper tipizzato.
Risultato dell’esecuzione del programma:

Python

Il SDK Python attualmente restituisce un dict, quindi usa res["id"] invece di res.id. Questo è diverso da openai-python, quindi fai attenzione durante la migrazione.
Risultato dell’esecuzione del programma:

Go

La risposta dell’SDK Go è uniformemente un map[string]any, non ci sono struct fortemente tipizzate, è necessario effettuare l’asserzione di tipo. Tutti gli accessori delle risorse sono catene di metodi: client.OpenAI().Chat().Completions().Create(...).
Risultato dell’esecuzione del programma:
Nelle risposte delle tre lingue, id, elapsed_ms, usage provengono tutti da: autenticazione PlatformGateway → API compatibile con OpenAI → registrazione della fatturazione. Il campo content è l’output reale del modello, utilizzando l’identificatore fisso ADC_*_OK per dimostrare che la risposta non è stata alterata dall’SDK.

Ordine di lettura consigliato

  1. Guida all’integrazione dell’SDK TypeScript —— codice che può essere eseguito dopo npm install.
  2. Guida all’integrazione dell’SDK Python —— tre modalità: sincrona, asincrona, streaming.
  3. Guida all’integrazione dell’SDK Go —— context.Context e flussi di canale in stile Go.
  4. Polling delle attività dell’SDK e risposte in streaming —— differenze nelle unità TaskHandle, dettagli di implementazione SSE, ritardi nei tentativi.
  5. SDK + Hook di pagamento X402 —— senza token, regolazione in base alle chiamate.

Come controllare il saldo rimanente

Puoi controllare il saldo rimanente del tuo account tramite Ace Data Cloud Console - Elenco delle applicazioni. Puoi visualizzare tutta la cronologia degli utilizzi e i dettagli delle spese tramite Ace Data Cloud Console - Cronologia utilizzi.

Scopri di più