GPUtw.ai — 台灣 GPU 雲端平台

列出 GPU 目錄

範例

curl https://gputw.ai/api/gpus/active

列出可用機器

範例

curl -H "Authorization: Bearer $GPUTW_API_KEY" "https://gputw.ai/api/nodes/available?catalogId=<catalog-id>"

建立執行個體

範例

curl -X POST https://gputw.ai/api/instances/create \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeId":"<node-id>","bandwidthMbps":100,"templateId":"<template-id>","ports":[8080]}'

部署公開自訂映像

以 customImage 取代 templateId，即可部署 Docker Hub、GHCR 等公開 registry 的任意映像。映像參考必須帶明確的非 latest tag 或 sha256 digest。啟用 sshEnabled 時以 root 搭配帳戶的 SSH 金鑰登入——金鑰會自動注入；若映像沒有 SSH 伺服器，系統會在啟動時自動安裝（映像需以 root 執行並內含 apk/apt/dnf 等套件管理器）。也可改為宣告 Web UI。選填 env 可注入環境變數；選填 args 會取代映像的 CMD（ENTRYPOINT 保留不變）。

範例

curl -X POST https://gputw.ai/api/instances/create \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeId":"<node-id>","bandwidthMbps":100,"customImage":{"dockerImage":"ghcr.io/acme/trainer:1.4.2","sshEnabled":true,"env":[{"name":"HF_TOKEN","value":"hf_xxx"}],"args":["--port","8080"]},"ports":[8080]}'

部署私有自訂映像

私有 registry 請加上 registryAuth。GPUtw 會轉成短效的 image pull secret，並在執行個體停止、失敗或終止時刪除已儲存的憑證。設定 webUiEnabled 並搭配 webUiLabel 與 webUiPort 即可開放瀏覽器介面。

範例

curl -X POST https://gputw.ai/api/instances/create \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeId":"<node-id>","bandwidthMbps":100,"customImage":{"dockerImage":"registry.example.com/team/app:2025-06-30","registryAuth":{"registry":"registry.example.com","username":"<user>","password":"<token>"},"webUiEnabled":true,"webUiLabel":"My App","webUiPort":8080}}'

Info

自訂映像部署需要 instances:create 權限。拉取映像時間會計入帳務，且 customImage 不可與 templateId/template 併用。公開映像請省略 registryAuth。env 最多 32 筆（名稱格式 [A-Za-z_][A-Za-z0-9_]*；平台保留的 PUBLIC_KEY、GATEWAY_KEY、NVIDIA_VISIBLE_DEVICES、NVIDIA_DRIVER_CAPABILITIES 會被拒絕）；args 最多 64 個。

停止執行個體

範例

curl -X POST https://gputw.ai/api/instances/stop \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"<instance-id>"}'

管理 HTTP 連接埠

範例

curl -X PATCH https://gputw.ai/api/instances/<instance-id>/ports \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ports":[8080,18080],"portAccess":{"8080":{"mode":"unlisted","password":"strong-password"},"18080":{"mode":"public"}}}'

建立 raw TCP exposure

將容器連接埠對應到 tcp.gputw.ai 上由平台指派的公開連接埠，回應會回傳指派的 endpoint。

範例

curl -X POST https://gputw.ai/api/instances/<instance-id>/exposures \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"tcp","containerPort":25565}'

建立 raw UDP exposure

將 protocol 設為 udp，適用於 datagram 服務（遊戲伺服器、WireGuard、QUIC 等）。系統會在 udp.gputw.ai 指派獨立的公開連接埠——TCP 與 UDP 的連接埠是分開配置的，因此相同號碼可能同時出現在兩者上。

範例

curl -X POST https://gputw.ai/api/instances/<instance-id>/exposures \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"udp","containerPort":51820}'

Warning

Raw TCP/UDP 端點是未驗證的 L4 直通連線。請使用本身具備驗證的服務，且切勿 raw 暴露未驗證的 web UI。以 DELETE /api/instances/{id}/exposures/{exposureId} 移除曝露，移除後該公開連接埠會釋出供重用。

REST API 快速開始