开发者
API 参考
使用会话或 API 密钥进行身份验证，并使用已实现的账户、报价、实例和计费端点。
8 分钟阅读 · 更新于身份验证
基础路径为 /api/v1. 浏览器请求使用登录时创建的 HttpOnly 会话 Cookie。脚本可以使用 Authorization: Bearer 后跟有效的 API 密钥。密钥拥有完整的账户权限，且仅在创建时显示一次。
本地界面使用 gh_demo_ 密钥。撤销密钥会立即阻止使用该密钥的新认证请求。请勿将密钥放入 URL 或浏览器端代码包中。
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }请求与重试规则
POST 和 PATCH 请求体为 JSON 对象，并带有 Content-Type: application/json。无参数操作请发送 {}。请求体限制为 32 KiB 文本。响应使用 Cache-Control: no-store。
部署、手动续订和撤回需要长度为 8–128 个字符的 Idempotency-Key。新的预期操作请使用新密钥，重试同一操作请复用同一密钥。切勿将其用于不同的请求体。重放响应会包含 replayed: true。
实例报价按当前目录价格计算，不预留容量。部署时发送 expectedPriceCents；若价格不匹配将返回 409，以便重新核对价格。
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}已实现的端点
所有账户资源均仅限于其所有者访问。可用性端点是公开的，仅公开目录快照，而非实时硬件探测。
| 方法 | /api/v1 之后的路径 | 用途 |
|---|---|---|
| POST | /auth/register · /auth/login | 用户名 + 密码；创建会话 |
| POST | /auth/recover | 用户名 + 未使用的代码 + 新密码 |
| POST | /auth/logout | 撤销当前浏览器会话 |
| GET | /me · /balance · /ledger | 账户、余额及最新 100 条记录 |
| GET / DELETE | /sessions · /sessions/:id | 列出活动会话或撤销其中一个 |
| GET | /availability | 公开目录与区域库存快照 |
| GET / POST | /deposit-quotes | 列出有效报价，或使用 asset + desiredUsdCents 创建报价 |
| POST | /demo/confirm-deposit | 报价 ID；仅限本地开发 |
| GET | /deposits · /withdrawals | 此账户最近的 100 条记录 |
| POST | /withdrawals | 资产 + 目的地 + amountUsdCents；幂等 |
| POST | /instance-quotes | GPU、数量、区域、镜像、期限和选项 |
| GET / POST | /instances | 列出分配或部署；部署是幂等的 |
| POST | /instances/:id/start · stop · release · renew | 生命周期操作；续订是幂等的 |
| PATCH | /instances/:id/auto-renew | 将 enabled 设置为 true 或 false |
| GET / POST | /ssh-keys · /api-keys | 列出或创建账户密钥 |
| DELETE | /ssh-keys/:id · /api-keys/:id | 吊销密钥 |
显式处理错误
错误包含 {error, message}：一个稳定的代码和一段可读的说明。400 表示无效输入，401 表示缺失或无效的身份验证，403 表示被拒绝的来源，404 表示未知或无主资源，409 表示余额/state/duplicate冲突，415 表示内容类型错误。
对于已过期的保证金报价，请创建另一份报价。对于已更改的实例状态，请在决定执行其他操作前重新加载实例。网络中断后，请复用操作密钥，而不是创建第二笔扣费。