---
title: TypeScript SDK
description: Официальный TypeScript SDK Clipia (npm clipia-ai 1.5.0) — установка, очередь генераций, каталог и оценка цены, проверка вебхуков, ошибки и CLI clipia.
icon: FileCode
---
Официальный TypeScript-клиент Clipia публикуется в npm как `clipia-ai`. Он работает на глобальном `fetch` (Node.js 18+), собран в ESM и CommonJS, поставляется с типами и командой `clipia` для терминала. Клиент покрывает очередь генераций (`queue.submit`, `queue.status`, `queue.result`), высокоуровневый `subscribe`, каталог моделей с оценкой цены и данные аккаунта.
Пакет называется `clipia-ai`, текущая версия — 1.5.0. Импорт клиента — из `clipia-ai`, отдельная лёгкая точка для проверки вебхуков — `clipia-ai/webhook`. Единственная зависимость времени выполнения, `commander`, нужна только CLI. Базовый URL — `https://api.clipia.ai`.
## Быстрый старт [#quickstart]
### Установка
```bash
npm i clipia-ai
```
### Клиент
Ключ — серверный секрет. Храните его в переменной окружения `CLIPIA_KEY`:
```ts
import { createClient } from 'clipia-ai';
const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });
```
`createClient` принимает `apiKey`, необязательный `baseUrl` (только `https://`), необязательную реализацию `fetch`, а также `maxRetries` (сколько раз `queue.submit` повторяет временный сбой, по умолчанию 2; `0` отключает повторы) и `retryDelayMs` (базовая пауза между повторами, по умолчанию 500 мс). Ключ отправляется в заголовке `Authorization: Bearer`.
### Генерация с ожиданием результата
`subscribe` ставит задачу в очередь и опрашивает статус, пока она не завершится:
```ts
const out = await clipia.subscribe('nano-banana-2', {
input: { prompt: 'неоновый город под дождём, кинематографичный свет' },
onQueueUpdate: (s) => console.log(s.status),
pollIntervalMs: 1000, // по умолчанию
timeoutMs: 600000, // по умолчанию
});
if (out.status === 'COMPLETED') {
console.log(out.output?.images?.[0]?.url); // ссылка на готовое изображение
console.log(out.cost); // стоимость в кредитах
} else {
console.error(out.error?.code, out.error?.message);
}
```
`subscribe` возвращает результат и при `FAILED`, поэтому проверяйте `status`. Кратковременные ошибки опроса (сеть, `429`, `5xx`) клиент повторяет сам, учитывая `Retry-After`. Если задача не завершилась за `timeoutMs`, выбрасывается `ClipiaApiError` с кодом `subscribe_timeout`; задача при этом продолжает выполняться, и её можно забрать по `request_id`.
## Ручное управление очередью [#queue]
```ts
const job = await clipia.queue.submit('nano-banana-2', {
input: { prompt: '...' },
webhookUrl: 'https://example.com/clipia-webhook', // необязательно
});
const status = await clipia.queue.status(job.request_id);
const result = await clipia.queue.result(job.request_id);
// result.pending === true, пока задача в IN_QUEUE или IN_PROGRESS
```
Все методы принимают необязательный `AbortSignal` для отмены HTTP-запроса: `queue.status(id, signal)`, а в `submit` и `subscribe` — поле `signal`. В версии 1.5 собственного таймаута на один HTTP-запрос у клиента нет: зависшее соединение держит вызов, пока не сработает ваш сигнал, поэтому в серверном коде передавайте `AbortSignal.timeout(30_000)` или похожий.
На каждый вызов `queue.submit` SDK генерирует новый `Idempotency-Key` (UUID v4) и сам повторяет временные сбои — ошибку сети, `429`, `500`, `502`, `503`, `504` — до `maxRetries` раз с тем же ключом, учитывая `Retry-After`: внутренний повтор не создаст вторую задачу. Но новый вызов `submit` в вашем коде получает новый ключ. Чтобы ваш собственный повтор попал в ту же задачу, передайте `idempotencyKey` и используйте его при повторе — см. [«Идемпотентность»](/ru/docs/api-reference/idempotency).
## Каталог, цена и аккаунт [#catalog]
```ts
const { data } = await clipia.models.list();
const model = await clipia.models.get('nano-banana-2');
const { credits } = await clipia.models.estimate('nano-banana-2', {
prompt: 'неоновый город под дождём',
});
const account = await clipia.account.get();
// { account_id, balance: { credits }, usage_30d: { requests, credits_spent } }
```
В `models.list()` могут прийти LLM-модели без `slug` — см. [«Каталог моделей»](/ru/docs/api-reference/models). Сумму `estimate` возвращает в кредитах до запуска, ничего не списывая.
## Проигнорированные параметры [#warnings]
Если в `input` есть ключ, который модель не применит (опечатка, параметр другой модели), `queue.submit` и `models.estimate` принимают запрос как обычно, а ключ возвращают в `warnings` — по элементу на каждый. Когда все параметры приняты, поля в ответе нет.
```ts
// job — ответ queue.submit из раздела «Ручное управление очередью»
for (const w of job.warnings ?? []) {
console.warn(w.code, w.parameter, w.message);
// unknown_parameter aspect_ration Parameter "aspect_ration" is not recognized and was ignored. …
}
// То же до запуска: оценка ничего не списывает
const estimate = await clipia.models.estimate('nano-banana-2', { prompt: '...' });
console.log(estimate.warnings); // undefined — все параметры приняты
```
Тип `InputWarning` и поле `warnings` описаны в SDK начиная с версии 1.5.0. `subscribe` возвращает итог генерации, предупреждений в нём нет: чтобы их прочитать, вызывайте `queue.submit` или `models.estimate`. Значения `code` и остальные правила — в разделе [«Проигнорированные параметры»](/ru/docs/api-reference/submit#warnings).
## Проверка вебхуков [#webhooks]
```ts
import { verifyWebhookSignature } from 'clipia-ai/webhook';
const ok = verifyWebhookSignature({
secret: process.env.CLIPIA_WEBHOOK_SECRET!,
headers: req.headers,
body: rawBody, // сырое тело запроса, до JSON.parse
// toleranceSeconds: 300 — по умолчанию
});
```
Функция возвращает `true` или `false`. Секрет вебхуков свой у каждого API-ключа — см. [«Вебхуки»](/ru/docs/api-reference/webhooks).
## Обработка ошибок [#errors]
Любой ответ не из диапазона 2xx превращается в `ClipiaApiError` с полями `status`, `code`, `type`, `message` и, если сервер прислал `Retry-After`, `retryAfterMs`. Сбой сети даёт `status: 0` и `code: "network_error"`.
```ts
import { ClipiaApiError } from 'clipia-ai';
try {
await clipia.queue.submit('nano-banana-2', { input: { prompt: '...' } });
} catch (e) {
if (e instanceof ClipiaApiError) {
console.error(e.status, e.code, e.type, e.message);
}
}
```
Коды ошибок — на странице [«Ошибки»](/ru/docs/api-reference/errors).
## CLI [#cli]
Пакет ставит команду `clipia`. Ключ берётся из переменной `CLIPIA_KEY` или флага `--key`; флаг виден в списке процессов, поэтому на общих машинах используйте переменную.
```bash
export CLIPIA_KEY=clipia_test_...
npx clipia models # каталог
npx clipia models nano-banana-2 # схема одной модели
npx clipia estimate nano-banana-2 --input '{"prompt":"кот"}'
npx clipia generate nano-banana-2 --input '{"prompt":"кот"}' --wait
npx clipia status
npx clipia result
npx clipia account
```
У `generate` есть флаги `--webhook ` и `--idempotency-key ` (один ключ на повторные запуски одной и той же задачи), у всех команд — `--base-url `.
## Песочница [#sandbox]
Ключ с префиксом `clipia_test_` возвращает заготовленный результат мгновенно и без списания кредитов — удобно для тестов и CI. Подробнее — в разделе [«Песочница»](/ru/docs/getting-started/sandbox).