Skip to main content
Las solicitudes a la API de Venice se autentican con claves de API tipo Bearer. Esta guía muestra cómo crear una clave desde el panel de Venice, almacenarla de forma segura y verificar que funciona.
Si estás construyendo un agente autónomo que necesita generar su propia clave con una wallet, utiliza en su lugar la guía Creación de claves de API para agentes autónomos.

​
Antes de comenzar

  • Inicia sesión en tu cuenta de Venice.
  • Asegúrate de que la cuenta tenga un saldo disponible antes de llamar a endpoints de pago. Puedes crear una clave antes de financiar la cuenta, pero las solicitudes a los modelos no se completarán hasta que la cuenta pueda consumir DIEM, créditos incluidos o USD.
1

Abrir la configuración de la API

Visita https://venice.ai/settings/api. También puedes abrir esta página desde la aplicación de Venice seleccionando API en tu configuración.El panel de configuración de la API muestra tus saldos, el nivel de la API, el uso y las claves de API existentes.
2

Iniciar una nueva clave

Selecciona Generate New API Key y luego configura la clave:
  • Description: Usa un nombre corto que identifique la aplicación, el entorno o la integración que utilizará esta clave.
  • API Key Type: Usa Inference Only para solicitudes normales a los modelos. Usa Admin solo cuando la clave deba gestionar claves de API de forma programática.
  • Expires at: Opcionalmente, establece una fecha de expiración. Si lo dejas en blanco, la clave no expirará automáticamente.
  • Epoch Consumption Limits: Opcionalmente, limita cuánto DIEM o USD puede gastar esta clave durante un epoch de 24 horas. Si lo dejas en blanco, la clave podrá usar el saldo disponible de la cuenta sujeto a los límites de tu cuenta.
3

Generar y copiar la clave

Haz clic en Generate. Venice mostrará la clave de API completa una sola vez.
Copia la clave de inmediato y guárdala en un lugar seguro. Después de cerrar el cuadro de diálogo, Venice solo mostrará metadatos identificativos como la descripción de la clave y los últimos caracteres. Si pierdes el valor secreto, elimina la clave y crea una nueva.
Pega la clave exactamente como se emitió. Usa el botón de copiar del cuadro de diálogo en lugar de seleccionar el texto a mano, para no recortar el primer o el último carácter ni arrastrar un salto de línea final. Cuando una herramienta te pida la clave en un campo de formulario, introduce solo la clave: sin el prefijo Bearer, sin comillas alrededor y sin espacios al principio o al final. Como el panel solo muestra los últimos caracteres una vez cerrado el cuadro de diálogo, nunca intentes reconstruir una clave perdida volviendo a escribir ese valor enmascarado.Añade la clave a tu entorno local o gestor de secretos:
4

Verificar la clave

Realiza una solicitud de bajo riesgo para confirmar que la autenticación funciona. Obtener límites de tasa y saldos de la clave de API no tiene coste y acepta cualquier tipo de clave. Úsalo en lugar de GET /models, que devuelve el catálogo de modelos con o sin clave y, por tanto, funciona incluso cuando tu clave es incorrecta:
Una respuesta exitosa devuelve tu nivel de API, tus saldos y tus límites de tasa, y data.accessPermitted indica si la clave puede consumir los endpoints de inferencia.Un 401 con AUTHENTICATION_FAILED significa que la propia clave fue rechazada. Imprime el valor almacenado y compáralo con los últimos caracteres que se muestran en el panel: las causas habituales son una copia parcial, un prefijo Bearer o comillas incluidos en el propio valor, o un espacio o salto de línea sobrante en cualquiera de los extremos. Confirma también que el encabezado dice Bearer <api-key> con exactamente un espacio entre ambos.
Deshabilitar el gasto en USD al crear una clave API en la aplicación de Venice establece tu límite de gasto en USD en cero para esa clave API. Las llamadas a la API pueden fallar con un error de saldo insuficiente cuando tu DIEM disponible o los créditos agrupados no puedan cubrir la solicitud, incluso si tu cuenta tiene saldo en USD.

​
Solución de errores de límite de gasto

Los límites de gasto por clave son independientes del saldo de tu cuenta. Una clave puede quedar bloqueada para gastar incluso cuando tu cuenta todavía tiene créditos en USD financiados, DIEM o créditos incluidos. Si una solicitud devuelve un 402 con uno de estos códigos, la causa es el propio límite de la clave y no el saldo de tu cuenta:
  • API_KEY_USD_SPEND_LIMIT_EXCEEDED — el límite de gasto en USD de la clave está establecido en cero (el gasto en USD se deshabilitó al crearla) o el epoch actual ha alcanzado su tope en USD.
  • API_KEY_DIEM_SPEND_LIMIT_EXCEEDED — la clave ha alcanzado su tope de DIEM para el epoch actual de 24 horas.
Para confirmar el estado actual de una clave, llama a Obtener límites de tasa y saldos de la clave de API e inspecciona data.accessPermitted, data.balances y los límites de consumo por clave. Para resolver el error, aumenta o elimina los Epoch Consumption Limits de la clave en venice.ai/settings/api, o llama a Actualizar clave de API con nuevos consumptionLimits. Los saldos a nivel de cuenta (USD, DIEM y créditos incluidos) son fuentes de pago independientes y se consumen automáticamente según estén disponibles; no es necesario elegir una en el momento de la solicitud. Consulta Códigos de error para ver la lista completa de respuestas relacionadas con la facturación.

​
Buenas prácticas

  • Crea claves separadas para desarrollo, staging y producción.
  • Prefiere claves Inference Only para aplicaciones que solo llaman a endpoints de modelos.
  • Mantén las claves Admin como excepcionales, con un alcance estricto y almacenadas únicamente en entornos confiables del lado del servidor.
  • Nunca subas claves de API al control de versiones ni las expongas en código del lado del cliente.
  • Establece fechas de expiración y límites de consumo para claves usadas en entornos temporales, compartidos o de mayor riesgo.
  • Elimina las claves que no uses y rota cualquier clave que pueda haber sido expuesta.

​
Gestión programática de claves

Las claves Admin pueden gestionar claves de API mediante los endpoints de la referencia de la API:

Crear clave de API

Crea una nueva clave de API estilo dashboard a partir de una clave admin existente.

Listar claves de API

Visualiza las claves activas y sus metadatos.

Actualizar clave de API

Actualiza la descripción de una clave, su fecha de expiración o los límites de consumo.

Eliminar clave de API

Revoca una clave que ya no se necesita.