GPU Rental 6분 소요

API 레퍼런스

GPU 인스턴스를 프로그래밍 방식으로 관리하세요. 인증, 인스턴스 생성, 상태 확인 등을 GPUnex API를 통해 수행하는 방법을 알아보세요.

API 키 발급

GPUnex API를 사용하면 웹 대시보드를 사용하지 않고도 GPU 인스턴스를 관리하고, 잔액을 확인하고, 워크플로우를 자동화할 수 있습니다. API 요청을 보내기 전에 API 키를 생성해야 합니다.

GPUnex 계정에 로그인하고 프로필 페이지 또는 대시보드 설정 패널로 이동합니다.
API Keys 섹션을 엽니다. 계정 설정 내에서 API Keys 탭 또는 카드를 찾으세요.
“새 API 키 생성”을 클릭합니다. 키에 설명적인 이름을 지정하라는 메시지가 표시됩니다. 키의 목적을 식별할 수 있는 의미 있는 이름을 선택하세요 — 예를 들어 “프로덕션 서버”, “CI/CD 파이프라인” 또는 “로컬 개발”. 이렇게 하면 나중에 여러 키를 관리하기 쉬워집니다.
API 키를 즉시 복사합니다. 키가 생성되면 한 번만 표시됩니다. 비밀번호 관리자 또는 암호화된 시크릿 저장소와 같은 안전한 위치에 복사하여 저장하세요. 이 단계 이후에는 전체 키를 다시 볼 수 없습니다.
키 범위와 폐기를 이해합니다. 각 API 키는 계정에 범위가 지정되며 계정 권한을 상속합니다. 다양한 애플리케이션이나 환경을 위해 여러 키를 만들 수 있습니다. 키가 유출되었거나 더 이상 필요하지 않은 경우 API Keys 섹션에서 언제든지 폐기할 수 있습니다. 키 폐기는 즉시 영구적으로 적용되며 해당 키를 사용하는 모든 요청이 거부됩니다.

인증

GPUnex API에 대한 모든 요청에는 Bearer 토큰 방식을 사용하여 API 키가 포함된 Authorization 헤더가 필요합니다.

헤더 형식:

Authorization: Bearer YOUR_API_KEY

터미널

$

API 키가 누락되었거나, 유효하지 않거나, 폐기된 경우 API는 401 Unauthorized 응답을 반환합니다:

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

모든 요청에 키가 포함되어 있는지 확인하세요. API는 세션 기반 인증이나 쿠키 기반 인증을 지원하지 않습니다.

주요 엔드포인트

GPUnex API는 RESTful 리소스를 기반으로 구성되어 있습니다. 모든 엔드포인트는 기본 URL https://api.gpunex.com/v1을 사용합니다. 아래는 사용 가능한 주요 엔드포인트 요약입니다.

메서드	엔드포인트	설명
GET	`/v1/instances`	모든 활성 및 최근 인스턴스를 나열합니다. 현재 상태, GPU 모델 및 구성 세부 정보가 포함된 인스턴스 객체 배열을 반환합니다.
POST	`/v1/instances`	새 GPU 인스턴스를 생성합니다. GPU 모델, 프레임워크 및 리전을 지정하는 JSON 본문이 필요합니다. USDC 잔액에서 요금이 차감됩니다.
GET	`/v1/instances/:id`	고유 ID로 특정 인스턴스의 상세 정보를 가져옵니다. SSH 연결 세부 정보, 런타임 메트릭 및 청구 정보가 포함됩니다.
DELETE	`/v1/instances/:id`	실행 중인 인스턴스를 종료합니다. 인스턴스가 중지되며 더 이상 요금이 부과되지 않습니다. 인스턴스의 저장되지 않은 데이터는 손실됩니다.
GET	`/v1/gpu-models`	마켓플레이스에서 현재 사용 가능한 모든 GPU 모델을 나열합니다. 가격, VRAM, 리전별 가용성 및 지원 프레임워크가 포함됩니다.
GET	`/v1/balance`	현재 USDC 지갑 잔액과 최근 거래 요약을 확인합니다.

모든 응답은 JSON 형식으로 반환됩니다. 성공적인 요청은 GET 요청에 대해 200 OK 상태 코드를, 리소스를 생성하는 POST 요청에 대해 201 Created 상태 코드를 반환합니다.

예제: 인스턴스 생성

새 GPU 인스턴스를 생성하려면 원하는 구성을 지정하는 JSON 본문과 함께 /v1/instances에 POST 요청을 보냅니다.

요청:

터미널

$

요청 본문 매개변수:

매개변수	타입	필수	설명
`gpu_model`	string	예	GPU 모델 식별자. 사용 가능한 옵션은 `/v1/gpu-models`를 참조하세요 (예: `H100_80GB`, `A100_80GB`, `L40S_48GB`, `L4_24GB`).
`framework`	string	예	사전 설치된 프레임워크 및 버전 (예: `pytorch-2.3`, `tensorflow-2.16`, `jax-0.4`).
`region`	string	예	인스턴스의 데이터센터 리전 (예: `us-east-1`, `eu-west-1`, `ap-southeast-1`).

예제 응답 (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"
}

인스턴스는 처음에 provisioning 상태입니다. GPU가 할당되고 환경이 준비되면 상태가 running으로 변경되고 ssh_command 필드에 연결 문자열이 채워집니다. 프로비저닝은 가용성에 따라 일반적으로 30초에서 2분이 소요됩니다.

예제: 인스턴스 상태 확인

인스턴스를 생성한 후 ID로 인스턴스 엔드포인트를 조회하여 언제든지 현재 상태를 확인할 수 있습니다.

요청:

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

예제 응답 (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"
}

상태 값:

상태	의미
`provisioning`	인스턴스가 설정 중입니다. GPU 리소스가 할당되고 프레임워크 환경이 준비되고 있습니다.
`running`	인스턴스가 활성 상태이며 사용할 준비가 되었습니다. SSH 접속이 가능합니다.
`stopping`	인스턴스가 종료 과정에 있습니다.
`terminated`	인스턴스가 중지되었으며 더 이상 요금이 발생하지 않습니다.
`error`	프로비저닝 또는 런타임 중에 오류가 발생했습니다. 이 상태가 지속되면 지원팀에 문의하세요.

속도 제한 및 모범 사례

속도 제한

GPUnex API는 공정한 사용과 플랫폼 안정성을 보장하기 위해 속도 제한을 적용합니다. 현재 제한은 다음과 같습니다:

일반 엔드포인트: API 키당 분당 120회 요청.
인스턴스 생성: API 키당 분당 10회 요청.
잔액 및 읽기 전용 엔드포인트: API 키당 분당 300회 요청.

속도 제한을 초과하면 API는 재시도까지 대기해야 하는 초 수를 나타내는 Retry-After 헤더와 함께 429 Too Many Requests 응답을 반환합니다.

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

모범 사례

통합을 안전하고 안정적으로 유지하려면 다음 지침을 따르세요.

클라이언트 측 코드에 API 키를 노출하지 마세요. 브라우저에서 실행되는 JavaScript, 모바일 앱 소스 코드 또는 공개적으로 접근 가능한 저장소에 API 키를 포함하지 마세요. API 키는 최종 사용자가 검사할 수 없는 서버 측 애플리케이션에서만 사용해야 합니다.

중요

클라이언트 측 코드, 브라우저 JavaScript 또는 공개 저장소에 API 키를 노출하지 마세요. API 키는 서버 측 애플리케이션에서만 사용해야 합니다.

환경 변수를 사용하세요. 소스 파일에 하드코딩하는 대신 환경 변수에 API 키를 저장하세요. 예:
```
export GPUNEX_API_KEY="your_api_key_here"
```
그런 다음 코드에서 참조합니다:
```
curl -H "Authorization: Bearer $GPUNEX_API_KEY" https://api.gpunex.com/v1/instances
```
키를 주기적으로 교체하세요. 보안 모범 사례로서 90일마다 새 API 키를 생성하고 이전 키를 폐기하세요. 이렇게 하면 키가 실수로 유출되더라도 영향을 제한합니다.
환경별로 별도의 키를 사용하세요. 개발, 스테이징, 프로덕션 환경에 대해 각각 별도의 API 키를 생성하세요. 이렇게 하면 하나의 키를 폐기해도 다른 환경에 영향을 주지 않습니다.

팁

개발, 스테이징, 프로덕션에 별도의 API 키를 사용하세요. 이렇게 하면 하나의 키를 폐기해도 다른 환경에 영향을 주지 않습니다.

오류를 적절하게 처리하세요. 애플리케이션에서 항상 HTTP 상태 코드를 확인하세요. 429 및 5xx 응답에 대해 지수 백오프와 함께 재시도 로직을 구현하세요. 429 이외의 4xx 오류는 재시도하지 마세요 — 이러한 오류는 요청 자체에 문제가 있음을 나타냅니다.
사용량을 모니터링하세요. API 호출 볼륨과 인스턴스 지출을 추적하세요. /v1/balance 엔드포인트를 사용하여 프로그래밍 방식으로 USDC 잔액을 모니터링하고 임계값 이하로 떨어지면 알림을 설정하세요.