VPS API 빠른 시작, API 키 만들기부터 서버 생성 curl 예제까지

1단계. API 키 만들기

API 키는 첫 결제가 끝난 뒤에 만들 수 있어요. 결제 방법은 USDT 결제 가이드에 있어요.

계정의 API 키 메뉴에서 API 키 만들기를 눌러요.
hvp_로 시작하는 키가 한 번만 표시돼요. 바로 복사해서 비밀번호 관리자에 저장해요.
화면에는 키의 끝자리만 남아서 어떤 키를 쓰는지 알아볼 수 있어요.
새 키 만들기를 누르면 새 키가 나오고 기존 키는 바로 사용할 수 없게 돼요.

키는 계정 전체를 다루는 열쇠라서 코드 저장소나 화면 공유에 보이지 않게 환경 변수로 넣어 써요. 이 가이드의 예제는 터미널에서 키를 변수 하나에 담아 두고 시작해요.

터미널

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 같은 운영체제와 app-docker, app-wordpress 같은 앱이에요.
추가 옵션: 자동 백업 비율, 추가 디스크 크기와 GB당 요금, DDoS 방어 요금이에요. 판매하지 않는 옵션은 null로 와요.

Ubuntu가 없다면 apt install -y jq, 맥은 brew install jq로 설치해요. 화면에서 고르는 것과 같은 목록이라, 사양별 차이는 요금 페이지에서 함께 보면 편해요.

4단계. 서버 만들기

POST /servers에 사양, 지역, 이미지, 이름을 JSON으로 보내요. 선택한 요금제의 첫 기간 요금을 결제하고 서버 만들기가 시작돼요.

터미널

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는 이 응답에 한 번 들어 있으니 바로 저장해요. 서버 페이지에서도 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개월을 더 결제해요. 정지된(suspended) 서버도 이 요청으로 다시 살아나요.
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 페이지에서 볼 수 있어요.

VPS API 빠른 시작, API 키 만들기와 첫 서버 만들기