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-aiInitialize 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 creditsIf 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.