TypeScript SDK

The official Clipia TypeScript SDK (npm clipia-ai) — install, initialize the client, submit a job and wait for the generation result.

The official Clipia TypeScript client ships on npm as clipia-ai. It is a standalone package with zero runtime dependencies, built on fetch, with ESM/CJS output and types. It wraps the public Queue API: submit a job, poll status, or use the high-level subscribe that polls to a terminal result for you.

Package name

On npm the package is clipia-ai, while the import name and CLI command are clipia. The base URL is https://api.clipia.ai, authenticated with an API key.

Quickstart

Install

npm i clipia-ai

Initialize the client

The key is a server-side secret; keep it in an environment variable:

import { createClient } from 'clipia-ai';

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

Submit + wait + result

The high-level subscribe enqueues a job and polls it to a finished result:

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
});

console.log(out.output);  // links to the finished media
console.log(out.cost);    // cost in credits

If you want manual control over the queue:

const job = await clipia.queue.submit('nano-banana-2', {
  input: { prompt: '...' },
});
const status = await clipia.queue.status(job.request_id);
const result = await clipia.queue.result(job.request_id);

Catalog, account and webhooks

await clipia.models.list();              // { data: [...] }
await clipia.models.get('nano-banana-2');
await clipia.account.get();              // { balance, usage_30d }

import { verifyWebhookSignature } from 'clipia-ai';
const ok = verifyWebhookSignature({ secret, headers, body });

Idempotency out of the box

The SDK generates an Idempotency-Key (UUID v4) on every submit by default, so retries are safe — the same key returns the same request_id, with no duplicates and no double charge.

Error handling

Errors are typed: ClipiaApiError extends Error with status, code and type fields.

import { ClipiaApiError } from 'clipia-ai';

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

Sandbox: a key prefixed clipia_test_ returns a fixed result instantly and with no charge — handy for tests and CI.