TypeScript SDK

Официальный TypeScript SDK Clipia (npm clipia-ai) — установка, инициализация клиента, постановка задачи в очередь и ожидание результата генерации.

Официальный TypeScript-клиент Clipia публикуется в npm как clipia-ai. Это standalone-пакет без runtime-зависимостей, на fetch, с ESM/CJS-сборкой и типами. Он оборачивает публичный Queue API: постановка задачи (submit), опрос статуса и высокоуровневый subscribe, который сам поллит до терминального результата.

Имя пакета

В npm пакет называется clipia-ai, а импорт-имя и CLI-команда — clipia. Базовый URL — https://api.clipia.ai, авторизация по API-ключу.

Быстрый старт

Установка

npm i clipia-ai

Инициализация клиента

Ключ — серверный секрет; держите его в переменной окружения:

import { createClient } from 'clipia-ai';

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

Submit + ожидание + результат

Высокоуровневый subscribe ставит задачу в очередь и опрашивает её до готового результата:

const out = await clipia.subscribe('nano-banana-2', {
  input: { prompt: 'неоновый город под дождём, кинематографичный свет' },
  onQueueUpdate: (s) => console.log(s.status),
  pollIntervalMs: 1000,   // по умолчанию
  timeoutMs: 600000,      // по умолчанию
});

console.log(out.output);  // ссылки на готовые медиа
console.log(out.cost);    // стоимость в кредитах

Если нужен ручной контроль очереди:

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

Каталог, аккаунт и вебхуки

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

Идемпотентность из коробки

SDK по умолчанию генерирует Idempotency-Key (UUID v4) на каждый submit, поэтому повторная отправка безопасна — тот же ключ вернёт тот же request_id, без дублей и двойного списания.

Обработка ошибок

Все ошибки приходят типизированными: ClipiaApiError extends Error с полями status, code и type.

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

Песочница: ключ с префиксом clipia_test_ возвращает фиксированный результат мгновенно и без списания — удобно для тестов и CI.