api.acedata.cloud에서의 채팅 완성, 이미지, 비디오, 음악, 검색, x402 등의 기능을 강타입 메서드로 캡슐화하여 HTTP, SSE, 작업 폴링, 오류 처리 및 재시도 백오프 작업을 수동으로 작성할 필요를 없앱니다.
이 장은 실제 접속 순서에 따라 구성됩니다: 먼저 콘솔에서 API 토큰을 얻고, 다음으로 언어를 선택하여 해당 장을 보고, 마지막으로 작업 폴링, 스트리밍 응답 및 X402 체인 상 결제의 고급 사용법을 살펴봅니다.
저장소 및 패키지
- SDK 소스 코드 (monorepo): https://github.com/AceDataCloud/SDK
- TypeScript:
@acedatacloud/sdk - Python:
acedatacloud - Go:
github.com/AceDataCloud/SDK/go - X402 클라이언트 (TypeScript):
@acedatacloud/x402-client - X402 클라이언트 (Python):
acedatacloud-x402
세 언어 능력 매트릭스
Go SDK의 멀티미디어 리소스와 작업 폴링은 현재 알파 단계에 있습니다(가짜 버전v0.0.0-20260505072132-4a3d921f9bb4),안정적인 기능은chat.completions입니다. 멀티미디어 시나리오는 TypeScript 또는 Python을 우선 선택하십시오.
SDK / MCP / 원시 HTTP / X402 사용 시기
SDK와 X402는 상호 배타적이지 않습니다: SDK는 동시에 “토큰 경로”와 “
paymentHandler 경로”를 지원합니다, 자세한 내용은 SDK + X402 결제 훅을 참조하십시오.
API 토큰 신청
SDK를 사용하려면 먼저 Ace Data Cloud 콘솔 - 애플리케이션 목록에서 API 토큰을 신청하십시오:
로그인 또는 등록하지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인하라는 초대가 표시됩니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아갑니다.
첫 번째 신청 시 무료 한도가 제공되어 Ace Data Cloud에서 제공하는 다양한 AI 서비스를 무료로 체험할 수 있습니다.
방금 받은 토큰을 복사하여 아래에서 통일하여 {token}으로 표기합니다.
통일 환경 변수
세 가지 언어의 SDK는 모두 동일한 환경 변수ACEDATACLOUD_API_TOKEN을 자동으로 읽습니다. 셸에서 export하여 SDK가 자동으로 가져오도록 하는 것이 좋습니다:
- TypeScript:
new AceDataCloud({ apiToken: '{token}' }) - Python:
AceDataCloud(api_token="{token}") - Go:
adc.NewClient(adc.WithAPIToken("{token}"))
주의: AceDataCloud 프로젝트 저장소에서는 관례적으로ACEDATACLOUD_API_KEY를 사용하지만(.env/ CI에서),이 세 가지 SDK는ACEDATACLOUD_API_TOKEN만 인식합니다. 환경에ACEDATACLOUD_API_KEY만 있는 경우 구성 시 명시적으로 전달하십시오.
30초 만에 시작하는 세 가지 예
아래 세 개의 코드는 동일한 작업을 수행합니다:gpt-4o-mini를 호출하여 정확히 ADC_*_OK로 응답하도록 합니다. 각 코드에는 실제 실행 결과가 첨부되어 있으며, 자신의 토큰으로 재현할 수 있습니다.
TypeScript
SDK는 현재 응답을프로그램 실행 결과:Record<string, unknown>으로 선언하고 있으며, 실행 시 일반 JSON 객체로, 필드에 직접 접근할 수 있습니다. 엄격한 TS 프로젝트에서 타입 오류가 발생하면 일시적으로as any를 사용하거나 SDK 작업 폴링 및 스트리밍 응답을 참조하여 사용자 정의 타입 래퍼를 만들 수 있습니다.
Python
Python SDK 현재 반환되는 것은프로그램 실행 결과:dict이므로res["id"]를 사용하고res.id를 사용하지 않습니다. 이 점은openai-python과 다르므로, 마이그레이션 시 주의해야 합니다.
Go
Go SDK의 응답은 모두프로그램 실행 결과:map[string]any로 통일되어 있으며, 강타입 구조체가 없으므로 직접 타입 단언을 해야 합니다. 모든 리소스 접근자는 메서드 체인으로:client.OpenAI().Chat().Completions().Create(...)입니다.
id, elapsed_ms, usage의 출처는 일관되며: PlatformGateway 인증 → 대상 OpenAI 호환 API → 청구 기록 작성. content 필드는 모델의 실제 출력이며, 고정 식별자 ADC_*_OK를 사용하여 응답이 SDK에 의해 변조되지 않았음을 증명합니다.
추천 읽기 순서
- TypeScript SDK 접속 튜토리얼 ——
npm install후 첫 번째 단락에서 실행할 수 있는 코드. - Python SDK 접속 튜토리얼 —— 동기, 비동기, 스트리밍 세 가지 사용법.
- Go SDK 접속 튜토리얼 —— Go 스타일의
context.Context와 채널 스트리밍. - SDK 작업 폴링 및 스트리밍 응답 —— TaskHandle 단위 차이, SSE 구현 세부사항, 재시도 백오프.
- SDK + X402 결제 훅 —— 토큰 없이 호출에 따라 블록체인 정산.
잔여 한도 확인 방법
Ace Data Cloud 콘솔 - 애플리케이션 목록을 통해 현재 계정의 잔여 한도를 확인할 수 있습니다. Ace Data Cloud 콘솔 - 사용 이력을 통해 모든 사용 이력과 요금 세부사항을 확인할 수 있습니다.더 알아보기
- 📦 SDK 모노레포 소스코드
- 🔌 X402 통합 가이드
- 🛠 MCP 서버 튜토리얼
- 📊 서비스 목록 및 가격

