Référence API

Obtenir votre clé API

L’API GPUnex vous permet de gérer des instances GPU, vérifier les soldes et automatiser vos flux de travail sans utiliser le tableau de bord web. Avant d’effectuer toute requête API, vous devez générer une clé API.

1. Connectez-vous à votre compte GPUnex et accédez à votre page Profil ou au panneau de paramètres du Tableau de bord.

2. Ouvrez la section Clés API. Recherchez l’onglet ou la carte Clés API dans les paramètres de votre compte.

3. Cliquez sur « Créer une nouvelle clé API ». Vous serez invité à donner un nom descriptif à la clé. Choisissez un nom significatif qui identifie l’usage prévu de la clé — par exemple, « Serveur de production », « Pipeline CI/CD » ou « Développement local ». Cela facilite la gestion de plusieurs clés par la suite.

4. Copiez votre clé API immédiatement. Une fois la clé générée, elle sera affichée une seule fois. Copiez-la et conservez-la dans un endroit sécurisé tel qu’un gestionnaire de mots de passe ou un coffre-fort de secrets chiffré. Vous ne pourrez plus visualiser la clé complète après cette étape.

5. Comprenez la portée et la révocation des clés. Chaque clé API est associée à votre compte et hérite des permissions de celui-ci. Vous pouvez créer plusieurs clés pour différentes applications ou environnements. Si une clé est compromise ou n’est plus nécessaire, vous pouvez la révoquer à tout moment depuis la section Clés API. La révocation d’une clé est immédiate et permanente — toutes les requêtes utilisant cette clé seront rejetées.

Authentification

Toutes les requêtes vers l’API GPUnex doivent inclure un en-tête Authorization avec votre clé API en utilisant le schéma Bearer token.

Format de l’en-tête :

Authorization: Bearer VOTRE_CLE_API

Si la clé API est manquante, invalide ou révoquée, l’API renverra une réponse 401 Unauthorized :

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

Assurez-vous que votre clé est incluse dans chaque requête. L’API ne prend pas en charge l’authentification basée sur les sessions ni l’authentification par cookies.

Points de terminaison principaux

L’API GPUnex est organisée autour de ressources RESTful. Tous les points de terminaison utilisent l’URL de base https://api.gpunex.com/v1. Voici un résumé des points de terminaison principaux disponibles.

Toutes les réponses sont renvoyées au format JSON. Les requêtes réussies renvoient un code d’état 200 OK pour les requêtes GET et un code d’état 201 Created pour les requêtes POST qui créent des ressources.

Exemple : Création d’une instance

Pour créer une nouvelle instance GPU, envoyez une requête POST à /v1/instances avec un corps JSON spécifiant la configuration souhaitée.

Requête :

Paramètres du corps de la requête :

Exemple de réponse (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"
}

L’instance aura initialement un statut provisioning. Une fois le GPU alloué et l’environnement prêt, le statut passera à running et le champ ssh_command sera renseigné avec votre chaîne de connexion. Le provisionnement prend généralement entre 30 secondes et 2 minutes selon la disponibilité.

Exemple : Vérification de l’état d’une instance

Une fois que vous avez créé une instance, vous pouvez vérifier son état actuel à tout moment en interrogeant le point de terminaison de l’instance avec son identifiant.

Requête :

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

Exemple de réponse (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"
}

Valeurs de statut :

Limites de débit et bonnes pratiques

Limites de débit

L’API GPUnex applique des limites de débit pour garantir une utilisation équitable et la stabilité de la plateforme. Les limites actuelles sont :

• Points de terminaison généraux : 120 requêtes par minute par clé API.
• Création d’instances : 10 requêtes par minute par clé API.
• Points de terminaison en lecture seule et solde : 300 requêtes par minute par clé API.

Si vous dépassez la limite de débit, l’API renverra une réponse 429 Too Many Requests avec un en-tête Retry-After indiquant le nombre de secondes à attendre avant de réessayer.

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

Bonnes pratiques

Suivez ces recommandations pour maintenir votre intégration sécurisée et fiable.

1. N’exposez jamais les clés API dans du code côté client. N’intégrez pas votre clé API dans du JavaScript exécuté dans le navigateur, dans le code source d’une application mobile, ou dans tout dépôt accessible publiquement. Les clés API ne doivent être utilisées que dans des applications côté serveur où elles ne peuvent pas être inspectées par les utilisateurs finaux.

2. Utilisez des variables d’environnement. Stockez votre clé API dans une variable d’environnement plutôt que de la coder en dur dans vos fichiers source. Par exemple :

   export GPUNEX_API_KEY="your_api_key_here"

   Puis référencez-la dans votre code :

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

3. Renouvelez les clés régulièrement. En tant que bonne pratique de sécurité, générez une nouvelle clé API tous les 90 jours et révoquez l’ancienne. Cela limite l’impact en cas de fuite involontaire d’une clé.

4. Utilisez des clés distinctes pour chaque environnement. Créez des clés API distinctes pour le développement, la pré-production et la production. Ainsi, la révocation d’une clé n’affecte pas les autres environnements.

5. Gérez les erreurs avec élégance. Vérifiez toujours les codes d’état HTTP dans votre application. Implémentez une logique de nouvelle tentative avec un délai exponentiel (exponential backoff) pour les réponses 429 et 5xx. Ne retentez pas les erreurs 4xx autres que 429 — celles-ci indiquent un problème avec la requête elle-même.

6. Surveillez votre utilisation. Suivez le volume de vos appels API et vos dépenses en instances. Utilisez le point de terminaison /v1/balance pour surveiller programmatiquement votre solde USDC et configurez des alertes s’il descend en dessous d’un seuil.