@acedatacloud/sdk es el SDK oficial de TypeScript / JavaScript de Ace Data Cloud, que encapsula todos los servicios en api.acedata.cloud en métodos tipados como client.openai.chat.completions.create(...), client.images.generate(...), client.search.google(...), etc., con soporte para flujos SSE, reintentos con retroceso y excepciones tipadas.
Se puede utilizar en Node.js, Deno, Bun y navegadores modernos (con bundler).
Dirección del código fuente y del paquete:
- Repositorio del SDK: https://github.com/AceDataCloud/SDK
- SDK de npm: https://www.npmjs.com/package/@acedatacloud/sdk
Instalación
- La versión del paquete es
2026.504.2(CalVer, la segunda revisión de la semana ISO 504 del año 2026). AceDataCloudes la clase principal utilizada para construir el cliente, accesible desde la exportación por defecto.
Preparar el API Token
Consulta Visión general del SDK - Solicitar API Token para obtener el token, luego en la shellexport:
apiToken, el SDK leerá automáticamente la variable de entorno ACEDATACLOUD_API_TOKEN. Si ya tienes ACEDATACLOUD_API_KEY en tu entorno (convenio del repositorio del proyecto), puedes pasarlo explícitamente: new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }).
Ejemplo 1: chat.completions (no en streaming)
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQAes el ID de respuesta compatible con OpenAI, que se puede buscar en el historial de uso en la consola.content ADC_TS_SDK_OKes el identificador fijo devuelto realmente por el modelo, que prueba que la respuesta no ha sido alterada por el SDK.- Una finalización de chat consume aproximadamente 22 tokens, cobrando según el precio unitario de gpt-4o-mini.
- El SDK declara la respuesta como
Record<string, unknown>, en tiempo de ejecución es un objeto JSON, el acceso por puntos como.id/.choices[0].message.contentfunciona en.mjs, Node REPL, Bun; en proyectos estrictos de TypeScript puede ser necesario usar(res as any).ido desactivarnoImplicitAnyen tsconfig.
Ejemplo 2: chat.completions (streaming SSE)
Al activarstream: true, create devuelve un iterador asíncrono, donde cada marco es un ChatCompletionChunk.
- La latencia del primer marco de 2481 ms es el tiempo que tardó el modelo en generar el primer token; los siguientes 12 marcos llegaron todos en 135 ms.
- Los 13 marcos juntos son
"1 2 3 4 5", cada token se genera en un marco separado + el último marco incluyefinish_reason. - El streaming no ahorra más tokens que el no streaming, pero la latencia del primer token se reduce significativamente, lo que es adecuado para interfaces de usuario en tiempo real.
Ejemplo 3: images.generate (NanoBanana)
client.images.generate({ provider: 'nano-banana', ... }) devuelve directamente de forma sincrónica, no es necesario pasar el parámetro wait — la API de NanoBanana genera de forma sincrónica.
image_urles una dirección estable en el CDN, que se puede usar directamente en<img src />o descargar.- En 16.6 segundos, la mayor parte del tiempo es para la inferencia del modelo, el costo del SDK local es despreciable.
trace_ides el ID de solicitud asignado por la plataforma, si hay un problema, proporciona este ID al servicio al cliente para una rápida localización.- Para servicios de tipo asíncrono (Midjourney, Sora, Veo, etc.) se necesita hacer polling de TaskHandle, consulta Polling de tareas del SDK y respuestas en streaming para más detalles.
Ejemplo 4: manejo de errores tipado
El SDK lanza los errores como subclases específicas según el estado HTTP (AuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError, etc.), por lo que se puede usar instanceof para realizar bifurcaciones precisas.
- El código 401 se asigna automáticamente a
AuthenticationError, y el código de negocio puede usarinstanceofpara realizar bifurcaciones precisas. code: invalid_tokenindica que la clave de API no es válida; compruebe las credenciales.- De igual forma: 429 →
RateLimitError, 400 →BadRequestErrory 5xx →InternalServerError.
Ejemplo 5: enrutamiento de múltiples modelos
El mismo cliente puede cambiar libremente entre varios servicios; basta con que el nombre del modelo sea el mismo.- Un código y un token para cubrir cuatro tipos de servicios de modelos: OpenAI / Google / DeepSeek / xAI.
- Esta vez
gemini-2.5-flashno devolvióADC_OK; se trata de una diferencia en el estilo de salida del propio modelo. El SDK no ha omitido silenciosamente nada y transmite fielmente las palabras originales del modelo a la aplicación. - El precio se factura según el precio por token de cada modelo.
Ejemplo 6: Búsqueda en Google
- Una sola solicitud obtiene 10 resultados orgánicos, el nombre del campo es
organic(noorganic_results). - La búsqueda se realiza a través del servicio Serp, se factura por uso.
- La misma instancia de cliente puede hacer chat y buscar, un solo token es suficiente.
Opciones de configuración
Uso en el navegador
@acedatacloud/sdk es un paquete ESM + ISO (isomórfico), se puede importar directamente en navegadores modernos con bundler. Nota: no codifiques en duro el API Token en el código del frontend. Se recomienda en el frontend:
- Usar X402
paymentHandler— la billetera del usuario paga por uso en USDC, sin necesidad de token. - O usar el SDK en tu propio servidor, el navegador solo llama a tu backend.
Avanzado: Polling de tareas y respuestas en streaming
- Servicios de tipo tarea (Midjourney, Sora, Veo, Suno): usar
TaskHandlepara hacer polling, detalles de unidad, tiempo de espera y reintentos ver SDK de polling de tareas y streaming. - Chat en streaming: el ejemplo 2 de esta página ya lo ha demostrado; audio / video en streaming también es compatible.
Avanzado: Ganchos de pago X402
Si no deseas solicitar un API Token y quieres pagar por uso en la cadena, puedes usarpaymentHandler:
createX402PaymentHandleren el lado de TypeScript acepta{ network, evmProvider, evmAddress, preferScheme? }(cadena EVM) o{ network: 'solana', solanaWallet }(Solana). En el servidor Node, si no haywindow.ethereum, usaviem’screateWalletClient(basado en clave privada) para envolver un proveedor compatible con EIP-1193 y luego pásalo; detalles sobre cómo hacerlo y resultados reales en la cadena ver SDK + ganchos de pago X402.

