Skip to main content
Ace Data Cloud oferece SDKs oficiais nas linguagens TypeScript / Python / Go, encapsulando as capacidades de chat completions, images, video, music, search, x402, etc., disponíveis em api.acedata.cloud, em métodos fortemente tipados, eliminando a necessidade de escrever manualmente HTTP, SSE, polling de tarefas, tratamento de erros e lógica de retry com backoff. Este capítulo está organizado na ordem de integração real: primeiro, obtenha o API Token no console, depois escolha a linguagem e veja o capítulo correspondente, e por último, veja o polling de tarefas, respostas em streaming e o uso avançado de pagamentos em blockchain X402.

Repositório e Pacotes

Matriz de Capacidades das Três Linguagens

Os recursos multimídia e o polling de tarefas do SDK Go estão atualmente em fase alpha (versão pseudo v0.0.0-20260505072132-4a3d921f9bb4), a capacidade estável é chat.completions. Para cenários multimídia, escolha preferencialmente TypeScript ou Python.

Quando usar SDK / MCP / HTTP nativo / X402

SDK e X402 não são mutuamente exclusivos: o SDK suporta simultaneamente o caminho “token” e o caminho “paymentHandler”, veja mais em SDK + Gancho de Pagamento X402.

Solicitar API Token

Para usar o SDK, primeiro vá ao Console Ace Data Cloud - Lista de Aplicativos e solicite um API Token: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o login ou registro, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo que você experimente gratuitamente os diversos serviços de IA oferecidos pelo Ace Data Cloud. Copie o Token que você obteve, que será referenciado como {token} a seguir.

Variáveis de Ambiente Unificadas

Os SDKs das três linguagens lerão automaticamente a mesma variável de ambiente ACEDATACLOUD_API_TOKEN, recomendando que você a export no shell, permitindo que o SDK a capture automaticamente:
Você também pode passá-la explicitamente ao construir o cliente, os nomes dos parâmetros correspondentes nas três linguagens são:
  • TypeScript: new AceDataCloud({ apiToken: '{token}' })
  • Python: AceDataCloud(api_token="{token}")
  • Go: adc.NewClient(adc.WithAPIToken("{token}"))
Nota: O repositório do projeto AceDataCloud convencionalmente usa ACEDATACLOUD_API_KEY (em .env / CI), mas esses três SDKs reconhecem apenas ACEDATACLOUD_API_TOKEN. Se o seu ambiente tiver apenas ACEDATACLOUD_API_KEY, passe-o explicitamente ao construir.

Exemplos Rápidos em 30 Segundos

As três seções de código fazem a mesma coisa: chamam gpt-4o-mini, pedindo que ele responda apenas com ADC_*_OK. Cada trecho inclui resultados reais de execução, que você pode reproduzir com seu próprio token.

TypeScript

O SDK atualmente declara a resposta como Record<string, unknown>, em tempo de execução é um objeto JSON comum, que pode ser acessado diretamente por campo. Em projetos TS rigorosos, se você encontrar erros de tipo, pode temporariamente usar as any, ou consultar Polling de Tarefas e Respostas em Streaming do SDK para criar um wrapper tipado.
Resultado da execução do programa:

Python

O SDK Python atualmente retorna um dict, então use res["id"] em vez de res.id. Isso é diferente do openai-python, e deve ser observado durante a migração.
Resultado da execução do programa:

Go

A resposta do SDK Go é uniformemente um map[string]any, não há struct de tipo forte, é necessário fazer a asserção de tipo manualmente. Todos os acessadores de recursos são encadeados: client.OpenAI().Chat().Completions().Create(...).
Resultado da execução do programa:
Nos três idiomas, os campos id, elapsed_ms e usage têm a mesma origem: através da autenticação do PlatformGateway → API compatível com OpenAI → gravação de registros de cobrança. O campo content é a saída real do modelo, usar o identificador fixo ADC_*_OK é para provar que a resposta não foi alterada pelo SDK.

Ordem de leitura recomendada

  1. Tutorial de integração do SDK TypeScript —— Código que pode ser executado após npm install.
  2. Tutorial de integração do SDK Python —— Três formas de uso: síncrono, assíncrono e em fluxo.
  3. Tutorial de integração do SDK Go —— Estilo Go de context.Context e fluxo de canal.
  4. Polling de tarefas do SDK e resposta em fluxo —— Diferenças de unidade de TaskHandle, detalhes de implementação do SSE, retrocesso de tentativas.
  5. SDK + Ganchos de pagamento X402 —— Sem token, liquidação por chamada em cadeia.

Como verificar o saldo restante

Através do Console Ace Data Cloud - Lista de Aplicativos, você pode verificar o saldo restante da conta atual. Através do Console Ace Data Cloud - Histórico de Uso você pode verificar todo o histórico de uso e detalhes de cobrança.

Saiba mais