Autenticación

Todas las llamadas de API que crean, consultan o facturan algo llevan tu clave de API en el encabezado Authorization. El catálogo público de modelos utilizado para evaluar el servicio es la única excepción: no necesita una clave.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La API nativa (/api/v1/*) acepta únicamente claves bearer, sin cookies ni parámetros de consulta.

Los endpoints de compatibilidad de texto y video (/v1, /v1beta) utilizan la misma clave y también aceptan el encabezado x-api-key de los SDK de Anthropic y x-goog-api-key de los SDK de Google GenAI, de modo que los SDK oficiales funcionan cambiando solo la URL base; consulta Texto y streaming. Esos dos encabezados no tienen efecto en /api/v1, y ningún endpoint acepta una clave en la cadena de consulta de la URL.

Las claves de API y la consola son independientes

Solo /api/v1, /v1 y /v1beta aceptan claves de API. La consola web utiliza su propia sesión del navegador. Por tanto, una sesión de la consola no puede utilizarse como clave de API y una clave filtrada no permite iniciar sesión en la consola. Enviar un tipo de credencial incorrecto siempre devuelve 401, nunca un error de permisos.

Formato de una clave

Un prefijo fijo sk-spicy- seguido de 48 caracteres hexadecimales en minúsculas.

El prefijo es deliberado: es preferible detectar la clave y recibir una notificación antes de descubrir que otra persona ya está gastando tu saldo.

Crear una clave

1. Abre Consola → Claves de API y pulsa Crear clave.
2. Dale el nombre del servicio que la utilizará (production backend, staging worker). Debes poder reconocerla cuando quieras revocarla.
3. Opcionalmente, abre Avanzado para configurar límites de gasto, una lista de modelos permitidos, una lista de IP permitidas y una fecha de vencimiento. Puedes cambiarlo todo después.
4. Copia la clave o pulsa Guardar como archivo y confirma que la guardaste. Una vez cerrado el cuadro de diálogo, la clave no puede volver a mostrarse.

Para crear claves necesitas el rol de propietario, administrador o desarrollador en el equipo. La clave pertenece al equipo seleccionado en la parte superior izquierda de la consola: su uso y sus límites se contabilizan en ese equipo. Cada equipo puede tener hasta 50 claves activas. Tu cuenta también necesita un correo verificado y saldo antes de que una clave pueda ejecutar trabajos de pago; consulta Configuración de cuenta.

Dónde guardar la clave

• En tu computadora, para pruebas: usa export SPICY_API_KEY="…" en la terminal (dura hasta que cierres esa ventana) o un archivo .env que cargue tu código. Añade .env a .gitignore antes de tu primer commit.
• En un servidor o plataforma de alojamiento: utiliza su configuración de secretos o variables de entorno y lee SPICY_API_KEY desde el entorno en tu código.
• Nunca pegues la clave en el código fuente, un chat, una captura de pantalla, un ticket de soporte ni el prompt de un asistente de IA.

Nunca distribuyas una clave al cliente

Esto también se aplica a los binarios móviles, clientes de escritorio, notebooks públicos, registros de CI y cualquier dato que termine en una salida de curl -v pegada en un ticket de soporte.

Las herramientas que tú utilizas en tu propio navegador son un caso diferente. La API acepta llamadas desde navegadores, así que las herramientas que ejecutas para ti, como la extensión de SillyTavern o una aplicación de roleplay donde pegas tu propia clave, pueden llamarla directamente. La regla anterior se refiere a incluir una clave en algo que otras personas cargan. Asigna a cada herramienta su propia clave con un límite diario, para poder consultar su gasto y revocarla de forma independiente.

Restricciones por clave

Configúralas en la consola al crear la clave o posteriormente. Se aplican en el servidor.

La tarjeta de cada clave muestra sus límites actuales, que puedes cambiar allí en cualquier momento.

Los límites incluyen tanto el dinero retenido para tareas en ejecución como el ya gastado, por lo que una clave puede alcanzar su límite mientras todavía hay tareas en curso. msg indica qué límite se alcanzó. Un 40202 cuyo msg menciona la cuota de la plataforma no corresponde a tu clave: crear otra no ayudará, así que reintenta más tarde.

La lista de IP permitidas se compara con tu dirección pública real tal como la ve nuestra red perimetral, no con la dirección del último proxy. Tu dirección de salida es la IP pública desde la que salen las solicitudes del servidor: la mayoría de las plataformas de alojamiento la muestran en su configuración de red, y en tu propia máquina puedes verla con curl https://ifconfig.me.

Las tareas pertenecen a la clave que las creó

La API solo permite ver una tarea con la clave de API que la creó. Con cualquier otra clave, incluso del mismo equipo:

Hay dos aspectos que no están vinculados a la clave. Los webhooks de una tarea se entregan incluso después de revocar la clave que la creó. Además, todas las tareas del equipo, con independencia de la clave que las creó, aparecen en Consola → Logs, donde los detalles de cada una muestran la Clave utilizada.

Rotación

• Una clave por entorno (producción / staging / local), para poder revocar una sin afectar a las demás.
• Rotación planificada: crea la clave nueva y envía con ella solo tareas nuevas. Mantén activa la antigua hasta que todas sus tareas hayan llegado a un estado final (como máximo, en el deadlineAt de cada tarea) y hayas recogido sus resultados; después revócala. Utiliza esta secuencia únicamente cuando todavía confíes en la clave antigua.
• La revocación es inmediata e irreversible. No hay una caché cuyo vencimiento debas esperar ni una forma de reactivar la clave: tendrás que crear otra.

Después de una filtración

Si hubo gastos inesperados, contáctanos desde Consola → Soporte con los ID de las tareas o los valores de request_id.

Cómo se presenta un fallo

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

El estado HTTP también es 401. Todos los fallos de autenticación devuelven code: 401, y msg indica de qué tipo se trata:

Usa code para la lógica, no el texto: la redacción puede cambiar y sigue tu idioma de errores. Consulta Errores para obtener más información sobre cómo distinguirlos.

Si la propia cuenta no puede llamar a la API (correo sin verificar o cuenta suspendida), recibes 403. Cambiar de clave no resolverá ese caso.