TypeScript SDK

The official Clipia TypeScript client is published on npm as clipia-ai. It runs on the global fetch (Node.js 18+), ships as ESM and CommonJS with types, and includes a clipia command for the terminal. It covers the generation queue (queue.submit, queue.status, queue.result), the high-level subscribe, the model catalog with price estimates, and account data.

QuickstartCopy Anchor Link

npm i clipia-ai

import { createClient } from 'clipia-ai';

const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });

const out = await clipia.subscribe('nano-banana-2', {
  input: { prompt: 'a neon city in the rain, cinematic lighting' },
  onQueueUpdate: (s) => console.log(s.status),
  pollIntervalMs: 1000, // default
  timeoutMs: 600000,    // default
});

if (out.status === 'COMPLETED') {
  console.log(out.output?.images?.[0]?.url); // link to the finished image
  console.log(out.cost);                     // cost in credits
} else {
  console.error(out.error?.code, out.error?.message);
}

subscribe also returns on FAILED, so check status. The client retries transient polling errors (network, 429, 5xx) on its own and honors Retry-After. If the job doesn't finish within timeoutMs, it throws a ClipiaApiError with code subscribe_timeout; the job keeps running and you can still fetch it by request_id.

Manual queue controlCopy Anchor Link

const job = await clipia.queue.submit('nano-banana-2', {
  input: { prompt: '...' },
  webhookUrl: 'https://example.com/clipia-webhook', // optional
});

const status = await clipia.queue.status(job.request_id);
const result = await clipia.queue.result(job.request_id);
// result.pending === true while the job is IN_QUEUE or IN_PROGRESS

Every method accepts an optional AbortSignal to cancel the HTTP request: queue.status(id, signal), and a signal field in submit and subscribe. In version 1.5 the client has no per-request timeout of its own: a hung connection holds the call until your signal fires, so pass AbortSignal.timeout(30_000) or similar in server code.

Catalog, price and accountCopy Anchor Link

const { data } = await clipia.models.list();
const model = await clipia.models.get('nano-banana-2');

const { credits } = await clipia.models.estimate('nano-banana-2', {
  prompt: 'a neon city in the rain',
});

const account = await clipia.account.get();
// { account_id, balance: { credits }, usage_30d: { requests, credits_spent } }

models.list() can include LLM models without a slug — see Model catalog. estimate returns the cost in credits before you run anything and charges nothing.

Ignored parametersCopy Anchor Link

If input contains a key the model will not apply (a typo, a parameter of another model), queue.submit and models.estimate accept the request as usual and return the key in warnings — one entry per key. When every parameter is accepted, the field is absent.

// job is the queue.submit response from the section above
for (const w of job.warnings ?? []) {
  console.warn(w.code, w.parameter, w.message);
  // unknown_parameter aspect_ration Parameter "aspect_ration" is not recognized and was ignored. …
}

// The same check before you run anything: an estimate charges nothing
const estimate = await clipia.models.estimate('nano-banana-2', { prompt: '...' });
console.log(estimate.warnings); // undefined — every parameter was accepted

The InputWarning type and the warnings field are described in the SDK starting with version 1.5.0. subscribe resolves with the generation result, which carries no warnings: call queue.submit or models.estimate to read them. The code values and the other rules are in Ignored parameters.

Verifying webhooksCopy Anchor Link

import { verifyWebhookSignature } from 'clipia-ai/webhook';

const ok = verifyWebhookSignature({
  secret: process.env.CLIPIA_WEBHOOK_SECRET!,
  headers: req.headers,
  body: rawBody, // the raw request body, before JSON.parse
  // toleranceSeconds: 300 — default
});

The function returns true or false. Each API key has its own webhook secret — see Webhooks.

Error handlingCopy Anchor Link

Any non-2xx response becomes a ClipiaApiError with status, code, type, message and, when the server sent Retry-After, retryAfterMs. A network failure gives status: 0 and code: "network_error".

import { ClipiaApiError } from 'clipia-ai';

try {
  await clipia.queue.submit('nano-banana-2', { input: { prompt: '...' } });
} catch (e) {
  if (e instanceof ClipiaApiError) {
    console.error(e.status, e.code, e.type, e.message);
  }
}

Error codes are listed on the Errors page.

CLICopy Anchor Link

The package installs a clipia command. It reads the key from the CLIPIA_KEY variable or the --key flag; the flag is visible in the process list, so prefer the variable on shared machines.

export CLIPIA_KEY=clipia_test_...

npx clipia models                      # catalog
npx clipia models nano-banana-2        # one model's schema
npx clipia estimate nano-banana-2 --input '{"prompt":"a cat"}'
npx clipia generate nano-banana-2 --input '{"prompt":"a cat"}' --wait
npx clipia status <request_id>
npx clipia result <request_id>
npx clipia account

generate also takes --webhook <url> and --idempotency-key <key> (one key across re-runs of the same job), and every command takes --base-url <url>.

SandboxCopy Anchor Link

A key prefixed clipia_test_ returns a canned result instantly with no credits charged — handy for tests and CI. See Sandbox.