Primeros pasos
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.
Cada solicitud a /v1/* se autoriza con una clave de API. La clave se crea en la Developer Console, se muestra una sola vez, está vinculada a su cuenta y cobra los créditos de su saldo. La cabecera recomendada es Authorization: Bearer clipia_live_….
Formas de cabecera
Puede enviar la clave de cualquiera de estas tres maneras. El servidor acepta todas, así que elija la que más le convenga.
curl https://api.clipia.ai/v1/account \
-H "Authorization: Bearer $CLIPIA_KEY"curl https://api.clipia.ai/v1/account \
-H "Authorization: Key $CLIPIA_KEY"curl https://api.clipia.ai/v1/account \
-H "X-Api-Key: $CLIPIA_KEY"| Forma | Cabecera | Nota |
|---|---|---|
| Bearer | Authorization: Bearer … | recomendada; solo acepta claves que empiezan por clipia_ |
| Key | Authorization: Key … | esquema alternativo; la palabra Key no distingue mayúsculas de minúsculas |
| X-Api-Key | X-Api-Key: … | si prefiere una cabecera dedicada |
Claves de producción y de prueba
El prefijo de la clave determina el entorno. Se elige al crear la clave.
| Prefijo | Entorno | Comportamiento |
|---|---|---|
clipia_live_… | producción | generación real, se cobran créditos |
clipia_test_… | entorno de pruebas | un ejemplo predefinido al instante; el coste se calcula, pero no se cobra |
Para pasar del entorno de pruebas a producción, basta con cambiar la clave, sin modificar el código. Consulte Entorno de pruebas para obtener más información.
Las claves de producción requieren créditos comprados
La generación con una clave clipia_live_ está disponible para las cuentas que hayan comprado créditos al menos una vez. Sin una compra, la solicitud devuelve 402 con el código insufficient_credits. Las claves de prueba (clipia_test_) funcionan sin pago.
Obtener una clave
- Abra la Developer Console y vaya a la pestaña API Keys.
- Haga clic en Create key, asígnele un nombre (hasta 100 caracteres) y elija el entorno: producción o prueba.
- Copie la clave y el secreto de firma de webhooks. Ambos se muestran una sola vez.
Una cuenta puede tener hasta 20 claves activas. Una vez alcanzado el límite, crear una clave devuelve 400 con el mensaje api_key_limit_reached: revoque una clave que ya no necesite y cree una nueva.
La clave es un secreto del lado del servidor
No coloque nunca la clave en un navegador, una aplicación móvil, un paquete de frontend o un repositorio público. Guárdela en un gestor de secretos o en variables de entorno del servidor. Si una clave se filtra, revóquela en la consola y cree una nueva.
Permisos de la clave
Cada clave se crea con los permisos generate y read. Los permisos no se eligen al crear la clave.
| Permiso | Qué permite |
|---|---|
generate | crear generaciones (POST /v1/models/{model}) y el chat con LLM de AI Gateway (POST /v1/chat/completions) |
read | reservado; hoy no habilita nada adicional |
- No necesita una clave aparte para el chat con LLM:
generatelo cubre. La generación de contenido multimedia y las llamadas a LLM consumen créditos del mismo saldo. - Cualquier clave válida puede leer el estado y el resultado de sus propias generaciones.
- El catálogo de modelos (
GET /v1/models), la estimación del coste y el saldo (GET /v1/account) no requieren permisos adicionales. - Una solicitud sin el permiso necesario devuelve
403 insufficient_scope.
Clave rechazada
Si la clave falta, es incorrecta o ha sido revocada, el servidor devuelve 401 invalid_api_key. Compruebe el prefijo del entorno y que la clave se envía en una de las tres cabeceras. El esquema Bearer solo acepta claves que empiezan por clipia_.
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.
Entorno de pruebas
El entorno de pruebas de la API de Clipia — una clave clipia_test_ ejecuta el ciclo completo de envío, estado, resultado y webhook sin cobrar créditos y devuelve una muestra lista.