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.