HELPER VPS

Démarrage rapide de l'API VPS : créer une clé API et un premier serveur

L'API HELPER VPS est une API REST qui échange du JSON en HTTPS. Avec une seule clé, vous consultez les offres, créez des serveurs, gérez l'alimentation, renouvelez et supprimez. Suivez le guide, de la première requête jusqu'à la création et la suppression d'un serveur.

Étape 1. Créer une clé API

Vous pouvez créer une clé API après votre premier paiement. Consultez le guide de paiement USDT pour savoir comment payer.

  • Dans le menu Clé API de votre compte, cliquez sur Créer une clé API.
  • Une clé commençant par hvp_ s'affiche une seule fois. Copiez-la aussitôt et enregistrez-la dans votre gestionnaire de mots de passe.
  • Seuls les derniers caractères de la clé restent à l'écran pour identifier la clé utilisée.
  • Cliquez sur Créer une nouvelle clé pour en obtenir une nouvelle ; l'ancienne est immédiatement désactivée.

La clé donne accès à tout le compte : utilisez-la via une variable d'environnement pour qu'elle n'apparaisse ni dans un dépôt de code ni lors d'un partage d'écran. Les exemples de ce guide commencent par placer la clé dans une variable du terminal.

Terminal
export HVP_KEY=hvp_VOTRE_CLE_ICI
export HVP=https://helpervps.com/api/v1

Étape 2. Authentification et première requête

Toutes les requêtes s'envoient sous l'adresse de base https://helpervps.com/api/v1, avec l'en-tête Authorization: Bearer clé. Pour la première requête, récupérez la liste de vos serveurs. Sans serveur, une liste vide [] est renvoyée.

Terminal
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Chaque compte peut envoyer jusqu'à 300 requêtes par minute, et 10 créations de serveur toutes les 10 minutes. Pour les vérifications d'état répétées, un intervalle de quelques secondes suffit largement. Toutes les réponses sont en JSON ; en cas d'erreur, vous recevez un code d'état avec un corps de la forme {"error": "code"}.

Étape 3. Choisir l'offre, la région et l'image

Toutes les valeurs à fournir pour créer un serveur viennent du catalogue. GET /catalog renvoie en une fois les offres en vente (plans), les régions (locations), les images (images) et les options (addons). Avec jq, il est facile de n'afficher que la partie utile.

Terminal
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'
  • Codes d'offre : comme s1 ou s2, ils indiquent le type et la taille. type vaut basic (SSD standard), fast (NVMe haute performance), cpu (CPU dédié) ou mem (haute mémoire). monthly est le tarif mensuel en dollars américains.
  • Codes de région : des noms de ville comme frankfurt, singapore ou seoul.
  • Codes d'image : des systèmes comme ubuntu-24-04, debian-13 ou almalinux-10, et des applications comme app-docker ou app-wordpress.
  • Options : taux de la sauvegarde automatique, tailles de disque supplémentaire et prix par GB, tarif de la protection DDoS. Une option non proposée vaut null.

Sans jq, installez-le avec apt install -y jq sur Ubuntu, ou brew install jq sur macOS. La liste est la même que celle de l'interface : comparez les offres sur la page des tarifs.

Étape 4. Créer un serveur

Envoyez le plan, l'emplacement, l'image et le nom au format JSON à POST /servers. Payez pour le premier terme de votre plan choisi et la création du serveur commence.

Terminal
curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

En cas de succès, vous recevez le code d'état 201 avec les informations du serveur. id est le code serveur de la forme S-XXXX-XXXX-XXXX, à utiliser dans toutes les requêtes suivantes. root_password figure une seule fois dans cette réponse : enregistrez-le aussitôt. Il reste aussi visible 7 jours sur la page du serveur.

  • label : le nom du serveur. Jusqu'à 40 caractères parmi les lettres latines, chiffres, points et traits d'union ; les autres caractères sont remplacés par un trait d'union.
  • backups : true active la sauvegarde automatique.
  • extra_disk_gb : la taille du disque bloc NVMe supplémentaire. Indiquez l'une des valeurs sizes_gb du catalogue (50, 100, 250, 500, 1000).
  • ddos_protection : true active la protection DDoS.

Le prix des options s'ajoute au tarif mensuel du serveur, affiché dans monthly de la réponse, et le renouvellement se fait automatiquement au même montant à chaque échéance. Chaque compte peut créer jusqu'à 10 serveurs.

Étape 5. Vérifier l'état et se connecter

Un nouveau serveur démarre à l'état creating, passe à running une fois prêt, puis l'adresse ipv4 est renseignée. La boucle ci-dessous vérifie l'état toutes les 10 secondes et affiche l'IP dès que l'état est running. Remplacez le code serveur par celui de votre serveur.

Terminal
ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

Le statut est l'un des suivants : creating, running, stopped, rebooting, installing, suspended ou check. suspended signifie que le serveur a été mis en pause car il n'a pas été renouvelé à la date de facturation, et check signifie que nous vérifions le résultat de la configuration du serveur. Une fois l'IP apparue, connectez-vous avec ssh root@IP. La méthode de connexion est dans le guide de première connexion.

Étape 6. Alimentation, renouvellement et suppression

Terminal
curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"
  • start : allume un serveur arrêté (stopped).
  • stop, reboot : éteint ou redémarre un serveur en marche (running).
  • renew : paie pour 1, 3, 6 ou 12 mois supplémentaires maintenant. Un serveur suspendu revient également avec cette requête.
  • DELETE : supprime le serveur et ses disques, et renvoie {"state": "deleted"}. La période restante du mois déjà payé n'est pas remboursée.

Si vous envoyez une action impossible dans l'état actuel, vous recevez 409 wrong_state, par exemple en envoyant start à un serveur déjà allumé. La réinstallation et la génération d'un nouveau mot de passe root se font sur la page du serveur. La marche à suivre est dans le guide de réinstallation.

Exécuter les mêmes étapes en Python

Le même enchaînement écrit en script Python ressemble à ceci. Il utilise la bibliothèque requests (pip install requests).

create_server.py
import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Codes d'erreur fréquents

  • 401 unauthorized : la clé est absente ou incorrecte. Vérifiez que l'en-tête a la forme Authorization: Bearer hvp_....
  • 403 not_allowed : s'ouvre une fois votre premier paiement confirmé.
  • 400 bad_request : un nom de champ ou une valeur est incorrect. Utilisez les codes exactement comme dans le catalogue.
  • 402 not_enough_balance : le montant du paiement est inférieur à 25 $. Envoyez à nouveau avec au moins 25 $.
  • 409 limit : vous avez atteint le nombre de serveurs autorisé pour ce compte.
  • 409 not_created : le serveur n'a pas pu être créé, et les frais sont retournés au crédit de votre compte.
  • 202 checking : nous vérifions le résultat de la configuration du serveur. Ne renvoyez pas la même requête ; consultez votre liste de serveurs. Le serveur sera terminé ou les frais seront retournés au crédit de votre compte.
  • 404 not_found : ce code serveur ou cette adresse n'existe pas dans votre compte.
  • 409 wrong_state : cette action n'est pas possible dans l'état actuel.
  • 429 rate_limited : la limite de requêtes par minute est atteinte. Patientez un instant avant de réessayer.

Tous les endpoints, champs de réponse et exemples sont réunis dans la documentation API. Les possibilités et usages de l'API sont présentés sur la page API VPS.

Guides complémentaires

Des réglages qu'il est bon de faire à la suite de ce guide.

Voir tous les guides