Referencia de API

Obtener su clave API

La API de GPUnex le permite administrar instancias GPU, verificar saldos y automatizar sus flujos de trabajo sin usar el panel web. Antes de realizar cualquier solicitud API, necesita generar una clave API.

1. Inicie sesión en su cuenta GPUnex y navegue a su página de Perfil o al panel de configuración del Dashboard.

2. Abra la sección de Claves API. Busque la pestaña o tarjeta de Claves API dentro de la configuración de su cuenta.

3. Haga clic en “Crear nueva clave API”. Se le pedirá que le dé a la clave un nombre descriptivo. Elija algo significativo que identifique el propósito de la clave — por ejemplo, “Servidor de producción”, “Pipeline CI/CD” o “Desarrollo local”. Esto facilita la gestión de múltiples claves posteriormente.

4. Copie su clave API inmediatamente. Una vez generada la clave, se mostrará exactamente una vez. Cópiela y guárdela en una ubicación segura como un administrador de contraseñas o un almacén de secretos cifrado. No podrá ver la clave completa nuevamente después de este paso.

5. Comprenda el alcance y la revocación de claves. Cada clave API está vinculada a su cuenta y hereda los permisos de su cuenta. Puede crear múltiples claves para diferentes aplicaciones o entornos. Si una clave se ve comprometida o ya no es necesaria, puede revocarla en cualquier momento desde la sección de Claves API. La revocación de una clave es inmediata y permanente — todas las solicitudes que utilicen esa clave serán rechazadas.

Autenticación

Todas las solicitudes a la API de GPUnex deben incluir un encabezado Authorization con su clave API usando el esquema Bearer token.

Formato del encabezado:

Authorization: Bearer SU_CLAVE_API

Si la clave API falta, es inválida o ha sido revocada, la API devolverá una respuesta 401 Unauthorized:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key. Please check your Authorization header."
}

Asegúrese de que su clave esté incluida en cada solicitud. La API no admite autenticación basada en sesiones ni autenticación basada en cookies.

Endpoints principales

La API de GPUnex está organizada alrededor de recursos RESTful. Todos los endpoints usan la URL base https://api.gpunex.com/v1. A continuación se presenta un resumen de los endpoints principales disponibles.

Todas las respuestas se devuelven en formato JSON. Las solicitudes exitosas devuelven un código de estado 200 OK para solicitudes GET y un código de estado 201 Created para solicitudes POST que crean recursos.

Ejemplo: Creación de una instancia

Para crear una nueva instancia GPU, envíe una solicitud POST a /v1/instances con un cuerpo JSON que especifique la configuración deseada.

Solicitud:

Parámetros del cuerpo de la solicitud:

Respuesta de ejemplo (201 Created):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "provisioning",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": null,
  "hourly_rate": "1.89",
  "currency": "USDC",
  "created_at": "2026-02-15T14:32:07Z"
}

La instancia tendrá inicialmente un estado de provisioning. Una vez que se asigne la GPU y el entorno esté listo, el estado cambiará a running y el campo ssh_command se completará con su cadena de conexión. El aprovisionamiento generalmente toma entre 30 segundos y 2 minutos dependiendo de la disponibilidad.

Ejemplo: Verificación del estado de una instancia

Una vez que haya creado una instancia, puede verificar su estado actual en cualquier momento consultando el endpoint de la instancia con su ID.

Solicitud:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.gpunex.com/v1/instances/inst_7f3a9b2c4d1e

Respuesta de ejemplo (200 OK):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "running",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": "ssh [email protected] -p 2222",
  "ip_address": "203.0.113.42",
  "hourly_rate": "1.89",
  "currency": "USDC",
  "uptime_seconds": 3847,
  "total_cost": "2.02",
  "created_at": "2026-02-15T14:32:07Z",
  "started_at": "2026-02-15T14:33:15Z"
}

Valores de estado:

Límites de frecuencia y mejores prácticas

Límites de frecuencia

La API de GPUnex aplica límites de frecuencia para garantizar un uso justo y la estabilidad de la plataforma. Los límites actuales son:

• Endpoints generales: 120 solicitudes por minuto por clave API.
• Creación de instancias: 10 solicitudes por minuto por clave API.
• Saldo y endpoints de solo lectura: 300 solicitudes por minuto por clave API.

Si excede el límite de frecuencia, la API devolverá una respuesta 429 Too Many Requests con un encabezado Retry-After que indica cuántos segundos esperar antes de reintentar.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 12 seconds.",
  "retry_after": 12
}

Mejores prácticas

Siga estas directrices para mantener su integración segura y confiable.

1. Nunca exponga las claves API en código del lado del cliente. No incruste su clave API en JavaScript que se ejecute en el navegador, código fuente de aplicaciones móviles o cualquier repositorio accesible públicamente. Las claves API solo deben usarse en aplicaciones del lado del servidor donde no puedan ser inspeccionadas por los usuarios finales.

2. Use variables de entorno. Almacene su clave API en una variable de entorno en lugar de codificarla directamente en sus archivos fuente. Por ejemplo:

   export GPUNEX_API_KEY="su_clave_api_aqui"

   Luego refiérase a ella en su código:

   curl -H "Authorization: Bearer $GPUNEX_API_KEY" https://api.gpunex.com/v1/instances

3. Rote las claves periódicamente. Como mejor práctica de seguridad, genere una nueva clave API cada 90 días y revoque la anterior. Esto limita el impacto si una clave se filtra inadvertidamente.

4. Use claves separadas para entornos separados. Cree claves API distintas para desarrollo, staging y producción. De esta manera, revocar una clave no afecta a otros entornos.

5. Maneje los errores con elegancia. Siempre verifique los códigos de estado HTTP en su aplicación. Implemente lógica de reintento con retroceso exponencial para respuestas 429 y 5xx. No reintente errores 4xx distintos de 429 — estos indican un problema con la solicitud en sí.

6. Monitoree su uso. Lleve un registro del volumen de llamadas API y del gasto en instancias. Use el endpoint /v1/balance para monitorear programáticamente su saldo USDC y configurar alertas si cae por debajo de un umbral.