TypeScript SDK

Официальный TypeScript-клиент Clipia публикуется в npm как clipia-ai. Он работает на глобальном fetch (Node.js 18+), собран в ESM и CommonJS, поставляется с типами и командой clipia для терминала. Клиент покрывает очередь генераций (queue.submit, queue.status, queue.result), высокоуровневый subscribe, каталог моделей с оценкой цены и данные аккаунта.

Быстрый стартСкопировать ссылку на раздел

npm i clipia-ai

import { createClient } from 'clipia-ai';

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

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.

Ручное управление очередьюСкопировать ссылку на раздел

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) или похожий.

Каталог, цена и аккаунтСкопировать ссылку на раздел

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 — см. «Каталог моделей». Сумму estimate возвращает в кредитах до запуска, ничего не списывая.

Проигнорированные параметрыСкопировать ссылку на раздел

Если в input есть ключ, который модель не применит (опечатка, параметр другой модели), queue.submit и models.estimate принимают запрос как обычно, а ключ возвращают в warnings — по элементу на каждый. Когда все параметры приняты, поля в ответе нет.

// 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 и остальные правила — в разделе «Проигнорированные параметры».

Проверка вебхуковСкопировать ссылку на раздел

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-ключа — см. «Вебхуки».

Обработка ошибокСкопировать ссылку на раздел

Любой ответ не из диапазона 2xx превращается в ClipiaApiError с полями status, code, type, message и, если сервер прислал Retry-After, retryAfterMs. Сбой сети даёт status: 0 и code: "network_error".

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

Коды ошибок — на странице «Ошибки».

CLIСкопировать ссылку на раздел

Пакет ставит команду clipia. Ключ берётся из переменной CLIPIA_KEY или флага --key; флаг виден в списке процессов, поэтому на общих машинах используйте переменную.

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 <request_id>
npx clipia result <request_id>
npx clipia account

У generate есть флаги --webhook <url> и --idempotency-key <key> (один ключ на повторные запуски одной и той же задачи), у всех команд — --base-url <url>.

ПесочницаСкопировать ссылку на раздел

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