获取您的 API 密钥
GPUnex API 允许您管理 GPU 实例、查询余额以及自动化工作流程，而无需使用 Web 仪表板。在发起任何 API 请求之前，您需要先生成一个 API 密钥。
-
登录您的 GPUnex 账户，然后导航到您的个人资料页面或仪表板设置面板。
-
打开 API 密钥部分。 在账户设置中找到 API Keys 标签页或卡片。
-
点击”Create New API Key”。 系统会提示您为密钥输入一个描述性名称。选择一个能标识密钥用途的有意义的名称——例如”Production Server”、“CI/CD Pipeline”或”Local Development”。这样可以方便您后续管理多个密钥。
-
立即复制您的 API 密钥。 密钥生成后，将仅显示一次。请复制它并存储在安全的位置，例如密码管理器或加密的密钥保管库中。此步骤之后您将无法再查看完整的密钥。
-
了解密钥范围和撤销。 每个 API 密钥的范围限定在您的账户内，并继承您的账户权限。您可以为不同的应用程序或环境创建多个密钥。如果某个密钥被泄露或不再需要，您可以随时在 API Keys 部分将其撤销。撤销密钥是即时且永久的——所有使用该密钥的请求都将被拒绝。
身份验证
所有对 GPUnex API 的请求都必须在 Authorization 头中使用 Bearer token 方案包含您的 API 密钥。
头部格式：
Authorization: Bearer YOUR_API_KEY如果 API 密钥缺失、无效或已被撤销，API 将返回 401 Unauthorized 响应：
{
"error": "unauthorized",
"message": "Invalid or missing API key. Please check your Authorization header."
}确保每个请求都包含您的密钥。API 不支持基于会话的身份验证或基于 Cookie 的身份验证。
核心端点
GPUnex API 围绕 RESTful 资源进行组织。所有端点使用基础 URL https://api.gpunex.com/v1。以下是可用核心端点的摘要。
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | /v1/instances | 列出所有活跃和近期的实例。返回包含当前状态、GPU 型号和配置详情的实例对象数组。 |
| POST | /v1/instances | 创建新的 GPU 实例。需要一个 JSON 请求体，指定 GPU 型号、框架和区域。费用将从您的 USDC 余额中扣除。 |
| GET | /v1/instances/:id | 通过唯一 ID 获取特定实例的详细信息。包括 SSH 连接详情、运行时指标和计费信息。 |
| DELETE | /v1/instances/:id | 终止正在运行的实例。实例将被停止，您将不再为其产生费用。实例上未保存的数据将丢失。 |
| GET | /v1/gpu-models | 列出市场上当前可用的所有 GPU 型号。包括定价、显存、各区域的可用性和支持的框架。 |
| GET | /v1/balance | 查询您当前的 USDC 钱包余额和近期交易摘要。 |
所有响应均以 JSON 格式返回。GET 请求成功时返回 200 OK 状态码，创建资源的 POST 请求成功时返回 201 Created 状态码。
示例：创建实例
要创建新的 GPU 实例，请向 /v1/instances 发送包含 JSON 请求体的 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 将返回 429 Too Many Requests 响应，并附带一个 Retry-After 头，指示在重试之前需要等待的秒数。
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 12 seconds.",
"retry_after": 12
}最佳实践
遵循以下指南，确保您的集成安全可靠。
- 切勿在客户端代码中暴露 API 密钥。 不要将 API 密钥嵌入在浏览器中运行的 JavaScript、移动应用程序源代码或任何公开可访问的代码仓库中。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 余额，并在余额低于阈值时设置提醒。