SDK de TypeScript

El cliente oficial de Clipia para TypeScript se publica en npm como clipia-ai. Funciona sobre el fetch global (Node.js 18+), se distribuye como ESM y CommonJS con tipos e incluye un comando clipia para la terminal. Cubre la cola de generación (queue.submit, queue.status, queue.result), el método de alto nivel subscribe, el catálogo de modelos con estimaciones de precio y los datos de la cuenta.

Inicio rápido

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: 'a neon city in the rain, cinematic lighting' },
  onQueueUpdate: (s) => console.log(s.status),
  pollIntervalMs: 1000, // valor por defecto
  timeoutMs: 600000,    // valor por defecto
});

if (out.status === 'COMPLETED') {
  console.log(out.output?.images?.[0]?.url); // enlace a la imagen generada
  console.log(out.cost);                     // coste en créditos
} else {
  console.error(out.error?.code, out.error?.message);
}

subscribe también devuelve el control con FAILED, así que compruebe status. El cliente reintenta por sí solo los errores transitorios de consulta (red, 429, 5xx) y respeta Retry-After. Si la tarea no termina dentro de timeoutMs, lanza un ClipiaApiError con el código subscribe_timeout; la tarea sigue ejecutándose y puede obtenerla igualmente por su request_id.

Control manual de la cola

const job = await clipia.queue.submit('nano-banana-2', {
  input: { prompt: '...' },
  webhookUrl: 'https://example.com/clipia-webhook', // opcional
});

const status = await clipia.queue.status(job.request_id);
const result = await clipia.queue.result(job.request_id);
// result.pending === true mientras la tarea está IN_QUEUE o IN_PROGRESS

Todos los métodos aceptan un AbortSignal opcional para cancelar la petición HTTP: queue.status(id, signal) y un campo signal en submit y subscribe.

Catálogo, precio y cuenta

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: 'a neon city in the rain',
});

const account = await clipia.account.get();
// { account_id, balance: { credits }, usage_30d: { requests, credits_spent } }

models.list() puede incluir modelos LLM sin slug: consulte Catálogo de modelos. estimate devuelve el coste en créditos antes de ejecutar nada y no cobra nada.

Parámetros ignorados

Si input contiene una clave que el modelo no aplicará (una errata, un parámetro de otro modelo), queue.submit y models.estimate aceptan la solicitud como de costumbre y devuelven la clave en warnings, con un elemento por cada clave. Cuando se aceptan todos los parámetros, el campo no aparece.

// job es la respuesta de queue.submit de la sección anterior
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. …
}

// La misma comprobación antes de ejecutar nada: la estimación no cobra nada
const estimate = await clipia.models.estimate('nano-banana-2', { prompt: '...' });
console.log(estimate.warnings); // undefined — se aceptaron todos los parámetros

El tipo InputWarning y el campo warnings están descritos en el SDK a partir de la versión 1.5.0. subscribe devuelve el resultado de la generación, que no incluye advertencias: para leerlas, llame a queue.submit o a models.estimate. Los valores de code y las demás reglas están en Parámetros ignorados.

Verificación de webhooks

import { verifyWebhookSignature } from 'clipia-ai/webhook';

const ok = verifyWebhookSignature({
  secret: process.env.CLIPIA_WEBHOOK_SECRET!,
  headers: req.headers,
  body: rawBody, // el cuerpo bruto de la petición, antes de JSON.parse
  // toleranceSeconds: 300 — valor por defecto
});

La función devuelve true o false. Cada clave de API tiene su propio secreto de webhook: consulte Webhooks.

Gestión de errores

Cualquier respuesta que no sea 2xx se convierte en un ClipiaApiError con status, code, type, message y, cuando el servidor ha enviado Retry-After, retryAfterMs. Un fallo de red da status: 0 y 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);
  }
}

Los códigos de error figuran en la página Errores.

CLI

El paquete instala un comando clipia. Lee la clave de la variable CLIPIA_KEY o del flag --key; el flag es visible en la lista de procesos, así que en máquinas compartidas es preferible la variable.

export CLIPIA_KEY=clipia_test_...

npx clipia models                      # catálogo
npx clipia models nano-banana-2        # esquema de un modelo
npx clipia estimate nano-banana-2 --input '{"prompt":"a cat"}'
npx clipia generate nano-banana-2 --input '{"prompt":"a cat"}' --wait
npx clipia status <request_id>
npx clipia result <request_id>
npx clipia account

generate también acepta --webhook <url>, y todos los comandos aceptan --base-url <url>.

Sandbox

Una clave con el prefijo clipia_test_ devuelve un resultado predefinido al instante sin cobrar créditos, lo que resulta práctico para pruebas y CI. Consulte Sandbox.