Primeros pasos
Inicio rápido
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.
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.
Cree una clave de API
Abra la Developer Console, 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.
export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxxxxLa 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.
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.
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. La cabecera Idempotency-Key hace que un reintento tras un fallo de red sea seguro: no se crea una segunda tarea.
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"
}'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);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)Ambos SDK añaden automáticamente un Idempotency-Key a cada envío. La respuesta devuelve un request_id y las URL de consulta:
{
"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.
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.
Consulta del estado. Consulte el status_url cada 1–2 segundos hasta que el estado sea terminal:
curl https://api.clipia.ai/v1/requests/764cabcf-.../status \
-H "Authorization: Bearer $CLIPIA_KEY"// 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"# 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"{ "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) |
Obtenga el resultado
Cuando el estado sea COMPLETED, solicite el resultado en response_url:
curl https://api.clipia.ai/v1/requests/764cabcf-... \
-H "Authorization: Bearer $CLIPIA_KEY"{
"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 para obtener más información.
Siguiente paso
Depure su integración sin gastar créditos con una clave de prueba. Antes de pasar a producción, lea las buenas prácticas.
Modelos de audio y voz
Los modelos de Clipia que ponen voz al texto y crean música, con desarrolladores, idiomas, voces, precios en créditos y consejos para elegir modelo y voz.
Autenticación
Cómo autorizar las solicitudes a la API de Clipia — la clave de API, tres formas de cabecera, claves de producción y de prueba, permisos de la clave y cómo guardarla de forma segura.