HELPER VPS

VPS API クイックスタート、API キーの作成と最初のサーバー作成

HELPER VPS API は、HTTPS で JSON をやり取りする REST API です。キー1つで、プランの取得、サーバーの作成、電源管理、更新、削除をすべて行えます。最初のリクエストから、サーバーを1台作成して削除するところまで進めてみましょう。

ステップ1. API キーを作成

最初の支払いが確認された後、APIキーを作成できます。支払い方法についてはUSDT支払いガイドを参照してください。

  • アカウントの API キーメニューで「API キーを作成」を押します。
  • hvp_ で始まるキーが1回だけ表示されます。すぐにコピーして、パスワードマネージャーに保存してください。
  • 画面にはキーの末尾だけが残るので、どのキーを使っているかを見分けられます。
  • 「新しいキーを作成」を押すと新しいキーが表示され、既存のキーはすぐに使えなくなります。

キーはアカウント全体を扱う鍵なので、コードのリポジトリや画面共有に映らないよう、環境変数に入れて使ってください。このガイドのサンプルは、ターミナルでキーを1つの変数に入れてから始めます。

ターミナル
export HVP_KEY=hvp_ここに自分のキー
export HVP=https://helpervps.com/api/v1

ステップ2. 認証と最初のリクエスト

すべてのリクエストはベースアドレス https://helpervps.com/api/v1 以下に送り、Authorization: Bearer キー ヘッダーを付けます。最初のリクエストとして、自分のサーバー一覧を取得してみましょう。サーバーがなければ、空のリスト [] が返ります。

ターミナル
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

リクエストはアカウントごとに1分あたり 300 回まで送信でき、サーバーの作成は10分あたり10回までです。状態を確認する繰り返しのリクエストは、数秒の間隔を空ければ十分です。レスポンスはすべて JSON で、エラーの場合はステータスコードとともに {"error": "コード"} の形で返ります。

ステップ3. プラン、リージョン、イメージを選ぶ

サーバー作成時に入れる値は、すべてカタログから取得します。GET /catalog は、販売中のプラン(plans)、リージョン(locations)、イメージ(images)、追加オプション(addons)を一度に返します。jq があれば、必要な部分だけを選んで見るのに便利です。

ターミナル
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'
  • プランコード: s1、s2 のように種類とサイズを表します。type は basic(SSD スタンダード)、fast(NVMe 高性能)、cpu(専用 CPU)、mem(大容量メモリ)です。monthly は米ドルの月額料金です。
  • リージョンコード: frankfurt、singapore、seoul のような都市名です。
  • イメージコード: ubuntu-24-04、debian-13、almalinux-10 のような OS と、app-docker、app-wordpress のようなアプリです。
  • 追加オプション: 自動バックアップの割合、追加ディスクのサイズと 1 GB あたりの料金、DDoS 対策の料金です。販売していないオプションは null で返ります。

jq がなければ Ubuntu は apt install -y jq、Mac は brew install jq でインストールします。画面で選ぶものと同じ一覧なので、プランごとの違いは料金ページとあわせて見ると便利です。

ステップ4. サーバーを作成

プラン、ロケーション、イメージ、名前をJSONでPOST /serversに送信します。選択したプランの最初の期間分を支払うと、サーバー作成が開始されます。

ターミナル
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"}'

成功すると、ステータスコード201とともにサーバーの情報が返ります。id は S-XXXX-XXXX-XXXX の形のサーバーコードで、以降のすべてのリクエストでこのコードを使います。root_password はこのレスポンスに1回だけ含まれるので、すぐに保存してください。サーバーページでも7日間確認できます。

  • label: サーバー名です。英字、数字、ピリオド、ハイフンで40文字まで使え、ほかの文字はハイフンに置き換わります。
  • backups: true なら自動バックアップが有効になります。
  • extra_disk_gb: 追加の NVMe ブロックディスクのサイズです。カタログの sizes_gb の値(50、100、250、500、1000)のいずれかを入れます。
  • ddos_protection: true なら DDoS 対策が有効になります。

オプションの料金はサーバーの月額料金に合算されてレスポンスの monthly に表示され、支払日ごとに同じ金額で自動更新されます。アカウントごとにサーバーを 10 台まで作成できます。

ステップ5. 状態の確認と接続

新しいサーバーは creating の状態で始まり、準備が終わると running になって ipv4 アドレスが入ります。下のループは10秒ごとに状態を確認し、running になると IP を表示します。サーバーコードは、自分のサーバーのコードに置き換えてください。

ターミナル
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

ステータスはcreating、running、stopped、rebooting、installing、suspended、checkのいずれかです。suspendedは請求日に更新されずに一時停止された状態、checkはサーバー設定の結果を確認している状態です。IPが表示されたら、ssh root@IPで接続します。接続方法は初回ログインガイドにあります。

ステップ6. 電源、更新、削除

ターミナル
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: 停止中(stopped)のサーバーを起動します。
  • stop、reboot: 実行中(running)のサーバーを停止、または再起動します。
  • renew：1、3、6、または12か月分を追加で支払います。一時停止されたサーバーもこのリクエストで復活します。
  • DELETE: サーバーとディスクを削除し、{"state": "deleted"} を返します。すでに支払った月の残り期間は返金されません。

現在の状態では実行できない操作を送ると、409 wrong_state が返ります。たとえば、すでに起動しているサーバーに start を送った場合です。再インストールと root パスワードの再作成は、サーバーページで行います。手順は再インストールガイドにあります。

Python で同じ手順を実行する

同じ流れを Python スクリプトで書くと、次のようになります。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)

よく見るエラーコード

  • 401 unauthorized: キーがないか、間違っています。ヘッダーが Authorization: Bearer hvp_... の形になっているか確認してください。
  • 403 not_allowed：最初の支払いが確認されると利用可能になります。
  • 400 bad_request: フィールド名や値が間違っています。コードはカタログの値をそのまま使ってください。
  • 402 not_enough_balance：支払額が$25未満です。最低$25で再度送信してください。
  • 409 limit: アカウントで作成できるサーバー数の上限に達しました。
  • 409 not_created：サーバーを作成できず、料金はアカウントクレジットに戻ります。
  • 202 checking：サーバー設定の結果を確認しています。同じリクエストを再送せず、サーバーリストを確認してください。サーバーが完成するか、料金がアカウントクレジットに戻ります。
  • 404 not_found: 自分のアカウントにないサーバーコードまたはアドレスです。
  • 409 wrong_state: 現在の状態では実行できない操作です。
  • 429 rate_limited: 1分あたりのリクエスト上限に達しました。少し待ってから送信してください。

すべてのエンドポイント、レスポンスのフィールド、サンプルは API ドキュメントにまとめています。API でできることと活用例は、VPS API のページでご覧いただけます。

あわせて読みたいガイド

このガイドに続けて設定しておくとよい内容です。

すべてのガイドを見る