---
title: Inicio rápido
description: Ejecute su primera generación de imagen con la API de Clipia en cuatro pasos, desde crear una clave hasta obtener el resultado, con ejemplos en cURL, TypeScript y Python.
icon: Rocket
---

Para generar su primera imagen con la API de Clipia, siga cuatro pasos: cree una clave de API, envíe una tarea con `POST /v1/models/{model}`, espere a que termine (webhook o consulta del estado) y obtenga el resultado. La URL base es `https://api.clipia.ai`. Cada generación es asíncrona: la solicitud pone una tarea en cola y devuelve su ID de inmediato.

<Steps>
<Step>
### Cree una clave de API

Abra la [Developer Console](/es/developer), vaya a la pestaña **API Keys** y haga clic en **Create key**. La clave completa se muestra **una sola vez**, así que cópiela de inmediato. Todos los ejemplos de esta documentación leen la clave de la variable de entorno `CLIPIA_KEY`.

```bash
export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

<Callout type="warn" title="La clave es un secreto del lado del servidor">
No incluya nunca la clave en un navegador, una aplicación móvil o un repositorio público. Utilícela solo desde su propio servidor.
</Callout>

<Callout type="info" title="Se requieren créditos comprados">
Una clave de producción `clipia_live_` puede generar una vez que la cuenta haya comprado créditos al menos una vez; de lo contrario, la solicitud devuelve `402 insufficient_credits`. Para desarrollar y depurar sin pagar, cree en su lugar una clave `clipia_test_`; consulte [Entorno de pruebas](/es/docs/getting-started/sandbox).
</Callout>
</Step>

<Step>
### Envíe una generación

Envíe `POST /v1/models/{model}` con un cuerpo `input`. Obtenga el slug del modelo en `GET /v1/models` o en el [catálogo de modelos](/es/docs/api-reference/models). La cabecera `Idempotency-Key` hace que un reintento tras un fallo de red sea seguro: no se crea una segunda tarea.

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
  -d '{
    "input": { "prompt": "a sunset over mountains, cinematic" },
    "webhook_url": "https://your-server.com/clipia/webhook"
  }'
```

</Tab>
<Tab value="TypeScript">

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

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

const job = await clipia.queue.submit("nano-banana-2", {
  input: { prompt: "a sunset over mountains, cinematic" },
  webhookUrl: "https://your-server.com/clipia/webhook",
});

console.log(job.request_id, job.status, job.cost);
```

</Tab>
<Tab value="Python">

```python
import os
from clipia import Clipia

clipia = Clipia(api_key=os.environ["CLIPIA_KEY"])

job = clipia.submit(
    "nano-banana-2",
    {"prompt": "a sunset over mountains, cinematic"},
    webhook_url="https://your-server.com/clipia/webhook",
)

print(job.request_id, job.status, job.cost)
```

</Tab>
</Tabs>

Ambos SDK añaden automáticamente un `Idempotency-Key` a cada envío. La respuesta devuelve un `request_id` y las URL de consulta:

```json
{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "status_url":   "https://api.clipia.ai/v1/requests/764cabcf-.../status",
  "response_url": "https://api.clipia.ai/v1/requests/764cabcf-...",
  "cost": 12
}
```

`cost` es el número de **créditos** reservados para la tarea. Se cobran si la generación tiene éxito y se reembolsan íntegramente si falla. Para conocer el precio antes de enviar la solicitud, utilice la [estimación del coste](/es/docs/api-reference/estimate).
</Step>

<Step>
### Espere a que termine

Hay dos formas de saber que una generación está lista.

**Webhook (recomendado).** Si indica un `webhook_url` al enviar la solicitud, Clipia envía un `POST` a su servidor cuando la tarea termina. Cada entrega se firma con HMAC-SHA256; consulte [Webhooks](/es/docs/api-reference/webhooks).

**Consulta del estado.** Consulte el `status_url` cada 1–2 segundos hasta que el estado sea terminal:

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl https://api.clipia.ai/v1/requests/764cabcf-.../status \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="TypeScript">

```ts
// subscribe() envía la tarea y consulta su estado hasta que termina
const result = await clipia.subscribe("nano-banana-2", {
  input: { prompt: "a sunset over mountains, cinematic" },
  onQueueUpdate: (s) => console.log(s.status, s.progress),
});

console.log(result.status); // "COMPLETED"
```

</Tab>
<Tab value="Python">

```python
# subscribe() envía la tarea y consulta su estado hasta que termina
result = clipia.subscribe(
    "nano-banana-2",
    {"prompt": "a sunset over mountains, cinematic"},
    on_queue_update=lambda s: print(s.status, s.progress),
)

print(result.status)  # "COMPLETED"
```

</Tab>
</Tabs>

```json
{ "request_id": "764cabcf-...", "status": "IN_PROGRESS", "queue_position": 0, "progress": 45 }
```

| Estado | Significado |
|--------|---------|
| `IN_QUEUE` | la tarea está en cola |
| `IN_PROGRESS` | en ejecución (`progress` de 0 a 100) |
| `COMPLETED` | terminada, obtenga el resultado |
| `FAILED` | ha fallado, créditos reembolsados |
| `CANCELED` | cancelada fuera de la API (estado terminal) |
</Step>

<Step>
### Obtenga el resultado

Cuando el estado sea `COMPLETED`, solicite el resultado en `response_url`:

```bash
curl https://api.clipia.ai/v1/requests/764cabcf-... \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

```json
{
  "request_id": "764cabcf-...",
  "status": "COMPLETED",
  "model": "nano-banana-2",
  "output": {
    "images": [
      {
        "url": "https://media.clipia.ai/....webp",
        "original_url": "https://media.clipia.ai/....png"
      }
    ]
  },
  "cost": 12,
  "created_at": "2026-10-09T12:00:00Z",
  "completed_at": "2026-10-09T12:00:18Z"
}
```

`url` es una copia optimizada para mostrar; `original_url` es el archivo original. En el caso del vídeo, `output` contiene `video: { url, original_url, thumbnail_url }`; en el del audio, `audio: { url }`. Consulte [Resultado](/es/docs/api-reference/result) para obtener más información.
</Step>
</Steps>

<Callout type="info" title="Siguiente paso">
Depure su integración sin gastar créditos con una [clave de prueba](/es/docs/getting-started/sandbox). Antes de pasar a producción, lea las [buenas prácticas](/es/docs/guides/best-practices).
</Callout>