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

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

<Callout type="info" title="Имя пакета">
В npm пакет называется `clipia-ai`, а импорт-имя и CLI-команда — `clipia`. Базовый URL — `https://api.clipia.ai`, авторизация по API-ключу.
</Callout>

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

<Steps>

<Step>

### Установка

```bash
npm i clipia-ai
```

</Step>

<Step>

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

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

```ts
import { createClient } from 'clipia-ai';

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

</Step>

<Step>

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

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

```ts
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);    // стоимость в кредитах
```

</Step>

</Steps>

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

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

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

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

<Callout type="info" title="Идемпотентность из коробки">
SDK по умолчанию генерирует `Idempotency-Key` (UUID v4) на каждый `submit`, поэтому повторная отправка безопасна — тот же ключ вернёт тот же `request_id`, без дублей и двойного списания.
</Callout>

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

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

```ts
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.