---
title: SDK de TypeScript
description: "El SDK oficial de Clipia para TypeScript (npm clipia-ai 1.5.0): instalación, cola de generación, catálogo y estimaciones de precio, verificación de webhooks, errores y la CLI clipia."
icon: FileCode
---

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.

<Callout type="info" title="Paquete y puntos de entrada">
El paquete es `clipia-ai`, versión actual 1.5.0. Importe el cliente desde `clipia-ai`; para verificar webhooks hay un punto de entrada ligero aparte, `clipia-ai/webhook`. La única dependencia en tiempo de ejecución, `commander`, la usa la CLI. La URL base es `https://api.clipia.ai`.
</Callout>

## Inicio rápido [#quickstart]

<Steps>

<Step>

### Instalación

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

</Step>

<Step>

### Cliente

La clave es un secreto del lado del servidor. Guárdela en la variable de entorno `CLIPIA_KEY`:

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

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

`createClient` recibe `apiKey`, un `baseUrl` opcional (solo `https://`) y una implementación de `fetch` opcional. La clave se envía en la cabecera `Authorization: Bearer`.

</Step>

<Step>

### Generar y esperar el resultado

`subscribe` pone la tarea en cola y consulta su estado hasta que termina:

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

</Step>

</Steps>

`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 [#queue]

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

<Callout type="info" title="Clave de idempotencia">
El SDK genera una `Idempotency-Key` nueva (UUID v4) en cada llamada a `queue.submit`. Por sí sola, eso solo protege esa llamada concreta: si vuelve a llamar a `submit` tras un error de red sin una clave propia, obtendrá una segunda tarea. Para que un reintento sea seguro, pase su propio `idempotencyKey` y reutilícelo en el reintento: consulte [Idempotencia](/es/docs/api-reference/idempotency).
</Callout>

## Catálogo, precio y cuenta [#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: '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](/es/docs/api-reference/models). `estimate` devuelve el coste en créditos antes de ejecutar nada y no cobra nada.

## Parámetros ignorados [#warnings]

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.

```ts
// 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](/es/docs/api-reference/submit#warnings).

## Verificación de webhooks [#webhooks]

```ts
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](/es/docs/api-reference/webhooks).

## Gestión de errores [#errors]

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

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

Los códigos de error figuran en la página [Errores](/es/docs/api-reference/errors).

## CLI [#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.

```bash
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 [#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](/es/docs/getting-started/sandbox).