Getting Started - 2DAICommunity/2dai-cloud-sdk GitHub Wiki

Getting Started

1. Install

npm install 2dai-cloud-sdk

Node 18+ (global fetch) or a modern browser. No other dependencies.

2. Get an API key

The whole process happens in the 2DAI dashboard:

  1. Have a 2DAI account — sign up at 2dai.io with your email, or sign in with your wallet. Any active account can create keys — there is no plan or tier requirement.
  2. In the dashboard's left sidebar, open Integrations.
  3. Switch to the API keys tab and click + New key.
  4. In the New API key dialog, fill in:
    • Label — a name for the integration (e.g. CI renderer, laptop agent). Labels are how you'll tell keys apart in the Usage tab later.
    • Scopes — what this key is allowed to do (least privilege wins):
      • read — list/search creations & folders, read queue status, stats, download
      • generate — run generations + upload media
      • manage — organise the drive (move, like, trash, restore, delete, folders & groups)
      • publish — publish / unpublish to the public feed
      • finance — read-only wallet data; off by default, and it can never move funds (see Keys & Scopes)
    • Spend cap (optional) — a per-key USD ceiling. Your account credit is always the real limit; the cap just stops one key from spending more than you allow.
  5. Create it, then copy the secret immediately — the full key (2dai_sk_…) is shown once and can never be retrieved again. If you lose it, revoke the key and create a new one.
  6. Store it in an environment variable (TWODAI_API_KEY), never in committed code or a client-side bundle.

Good to know:

  • An account can hold up to 20 active keys; revoke any key from the same tab (revocation is instant).
  • Generations burn your account credit — check the dashboard's Credit section (or client.me() → creditUsd) before generating.
  • See Keys & Scopes for the scope → method matrix, spend caps and rotation hygiene.

3. Create a client

import { Client } from '2dai-cloud-sdk';

const client = new Client({ apiKey: process.env.TWODAI_API_KEY! });

Check who you are and how much credit you have:

const me = await client.me();
console.log(me.username, me.creditUsd, me.tier);
console.log(me.key.scopes, me.key.spentUsd, me.key.spendLimitUsd);

4. Your first generation

const gen = await client.generate.image({
  prompt: 'a lighthouse at dusk, long exposure',
  aspectRatio: '16:9',
});

console.log(gen.creationId, gen.width, gen.height, gen.costUsd);
await client.download(gen, { savePath: './lighthouse' }); // → ./lighthouse.jpg

Configuration

new Client({
  apiKey: '2dai_sk_…',   // required
  baseUrl,               // default 'https://dapp.2dai.io:444'
  timeoutMs,             // per-request network timeout, default 60000
  maxRetries,            // idempotent GET retries on 429/5xx, default 2
  fetch,                 // inject a custom fetch (tests / proxies)
  integration,           // 'sdk' (default) | 'mcp' — official 2DAI integrations
  integrationVersion,    // that integration's own semver, e.g. '1.4.0'
});

Leave integration unset. It replaces the free-form userAgent option, which is gone: the server stamps each creation's source from the User-Agent, and the dashboard uses source to fill its SDK / MCP collections and to label a row's origin. That makes the label data, not a comment — an open string invited typos and let anyone claim to be a first-party integration. 'mcp' belongs to the official 2DAI MCP server; everything you write lands as sdk, which is what you want. If you do set integrationVersion, it must be a real 1.2.3 (a prerelease or build suffix is allowed) — the SDK substitutes 0.0.0 for anything malformed rather than dropping it, because the token has to match name/x.y.z for the server to recognise the integration at all.

Generation submits are never auto-retried (they may charge). The SDK attaches an idempotency token so that if you retry an identical call within a few seconds, the server de-duplicates it.