API de Clipia · v1

API para desarrolladores

Genere imágenes y vídeo mediante la API: cola asíncrona, webhooks firmados, SDK de TypeScript y Python, una CLI y facturación basada en créditos. Los mismos modelos que en la aplicación.

Obtener una clave de API Descargar OpenAPI

API de cola: submit → poll / webhook
TS · Python · CLI: SDK oficiales
Imágenes y vídeo: un único punto de entrada

API de cola

Una cola asíncrona: submit encola un trabajo y devuelve un request_id al instante. Obtenga el resultado consultando status_url o de inmediato mediante un webhook.

SDK y CLI

Clientes oficiales para TypeScript y Python con un subscribe de alto nivel, además de una CLI para scripts y comprobaciones rápidas.

Sandbox

Una clave clipia_test_ devuelve un resultado fijo al instante: depure el análisis de respuestas, el polling y los webhooks sin gastar créditos.

Webhooks firmados

Al finalizar, Clipia envía un POST firmado con HMAC-SHA256. Verifique la firma con el cuerpo sin procesar; los SDK incluyen una utilidad lista para usar.

Idempotencia

El encabezado Idempotency-Key hace seguros los reintentos: la misma clave devuelve el mismo request_id, sin trabajos duplicados ni doble cobro.

Límites transparentes

Límites por clave: solicitudes por minuto y generaciones simultáneas. El estado actual aparece en los encabezados RateLimit-* de cada respuesta.

Guarde su clave en la variable de entorno CLIPIA_KEY

export CLIPIA_KEY="clipia_live_xxxxxxxxxxxxxxxxxxxxxx"

# Submit a text-to-image job
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Key $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'

# Poll the request until status == COMPLETED, then read the result
curl https://api.clipia.ai/v1/requests/<request_id> \
  -H "Authorization: Key $CLIPIA_KEY"

Los SDK generan por defecto una Idempotency-Key (UUID v4) en cada submit, por lo que los reintentos son seguros desde el primer momento.

TypeScript

npm i clipia-ai

Python

pip install clipia

CLI

npx clipia account

Los nombres de los paquetes son definitivos; la publicación en npm y PyPI forma parte del lanzamiento.

Código fuente en GitHub:clipia-js clipia-python clipia-mcp

Encabezado de la solicitud

Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxx

La clave es un secreto del lado del servidor

Equivale a la contraseña de su saldo de créditos. Haga las llamadas solo desde su propio servidor y guarde la clave en una variable de entorno o en un gestor de secretos. Nunca la ponga en un navegador, una aplicación móvil ni un repositorio público.

Una clave activa se muestra una sola vez al crearla. Después, la lista muestra solo el prefijo.

HTTP	Código	Cuándo	Reintento
400	`invalid_request`	Cuerpo o parámetros no válidos	No reintentar
401	`invalid_api_key`	Clave ausente, no válida o revocada	No reintentar
402	`insufficient_credits`	No hay suficientes créditos en el saldo	No reintentar
402	`subscription_required`	Tiene créditos, pero están bloqueados: se requiere una suscripción activa	No reintentar
403	`insufficient_scope`	La clave no tiene el alcance necesario	No reintentar
404	`not_found`	request_id o modelo desconocido	No reintentar
409	`idempotency_key_reuse`	Conflicto de idempotencia	No reintentar
422	`model_input_invalid`	Los parámetros no coinciden con el modelo	No reintentar
429	`rate_limit_exceeded`	Se superó el límite de solicitudes	Con backoff
5xx	`internal_error`	Error interno o indisponibilidad temporal	Con backoff

Verificación de la firma

Cada entrega se firma con HMAC-SHA256 en el encabezado X-Clipia-Signature. Verifique la firma con el cuerpo sin procesar de la solicitud antes de analizar el JSON; los SDK incluyen una utilidad de verificación.

Entrega y reintentos

Responda con 2xx en un plazo de 10 segundos. Si falla, las entregas se reintentan con backoff exponencial. Un mismo evento puede llegar de nuevo, así que procese los webhooks de forma idempotente por request_id.

Endpoint de MCP

https://mcp.clipia.ai/mcp

Claude Code

claude mcp add --transport http clipia https://mcp.clipia.ai/mcp --header "Authorization: Bearer YOUR_KEY"

Cursor (mcp.json)

{
  "mcpServers": {
    "clipia": {
      "url": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Herramientas

Herramienta	Qué hace
`generate_image`	Envía un trabajo de generación de imágenes
`generate_video`	Envía un trabajo de generación de vídeo
`generate_audio`	Envía un trabajo de generación de texto a voz
`generate_music`	Envía un trabajo de generación de música
`wait_generation`	Espera hasta que finalice una generación
`get_generation`	Estado y resultado de una generación por ID
`list_models`	Lista los modelos disponibles y sus precios en créditos
`get_model`	Parámetros y precio de un modelo concreto
`get_balance`	Saldo actual de créditos
`search_templates`	Busca en la biblioteca de plantillas de prompts

Las claves con el prefijo clipia_test_ se ejecutan en el sandbox: respuestas simuladas al instante, sin cobro de créditos.

Cree su clave en la consola para desarrolladores, pestaña Claves de API.

API para desarrolladores

Lo que le ofrece la API

API de cola

SDK y CLI

Sandbox

Webhooks firmados

Idempotencia

Límites transparentes

Inicio rápido en 5 minutos

Instale el SDK

Autenticación

Gestión de errores

Webhooks en lugar de polling

Verificación de la firma

Entrega y reintentos

MCP para Claude Code y agentes de IA

Próximos pasos

Referencia completa

Obtener una clave de API

Para empresas