# API

使用權杖認證，然後透過簡單的 JSON 進行搜尋、租用、管理和付款。

## 基礎知識

- 基礎 URL：`$ARRAKIS_URL`。所有請求和響應都是 JSON。
- 使用 `Authorization: Bearer ark_...` 進行認證。權杖決定所操作的帳戶。
- 錯誤以 `{"detail": "..."}` 的形式返回，並帶有明確的狀態碼：401（權杖）、402（餘額或支出上限）、403（許可權範圍）、404、409、422（輸入）、429（請求過於頻繁）、503（尚未開放租用）。
- 完整的介面定義見 [/openapi.json](/openapi.json)；可在[互動式參考](/docs/reference)中試用各個呼叫。

## 權杖和許可權範圍

| 許可權範圍 | 允許 |
|---|---|
| `read` | 搜尋機器；檢視你的機器、儲存磁碟區和映像 |
| `rent` | 租用、重啟和停止機器 |
| `manage` | 建立和撤銷權杖；儲存 SSH 金鑰和映像 |
| `billing` | 餘額、付款、自動充值、緊急停止 |

在 **API & agents** 頁面或透過 `POST /v1/tokens` 建立權杖。權杖可以帶有 `spend_limit_usd`、`max_rental_hours` 和 `expires_at`。權杖只能建立許可權範圍不超過自身、額度不超出自身上限的權杖。

## 無需權杖

```sh
curl $ARRAKIS_URL/v1/market/summary
```

按 GPU 系列返回實時價格和可用情況。

## 租用機器

```sh
curl -X POST $ARRAKIS_URL/v1/instances \
  -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \
  -d '{"node_id": "<node>", "name": "eval", "ssh_public_key": "ssh-ed25519 AAAA...",
       "termination_hours": 4, "idempotency_key": "eval-2026-10-14"}'
```

用 `GET /v1/gpus` 找到 `node_id`；其中的 `tier` 會標明 `on_demand` 或 `spot`。餘額必須夠支付第一個小時（否則返回 402），這一小時在機器開始執行時扣費（最少計費 1 小時）。傳送 `max_price_per_gpu_hour`，即可按不高於你看到的價格（`GET /v1/gpus/{node_id}/price`）租用：如果實時價格更高，則不會租用任何機器，並返回 409。

## 主要路由

| 方法 | 路徑 | 功能 |
|---|---|---|
| GET | `/v1/market/summary` | 按 GPU 系列的實時價格（公開） |
| GET | `/v1/market/history` | 每個 GPU 系列的逐小時價格，JSON 格式，或用 `format=csv` 獲取 CSV（公開） |
| GET | `/v1/models/fit?model=owner/name` | Hugging Face 模型需要的 GPU 視訊記憶體，以及當前能放下它的最便宜 GPU（公開） |
| GET | `/v1/gpus` | 可租用的機器，最便宜的排在前面 |
| GET | `/v1/gpus/{node_id}/price` | 機器當前的實時價格 |
| POST | `/v1/instances` | 租用機器 |
| GET | `/v1/instances`, `/v1/instances/{id}` | 你的機器 |
| POST | `/v1/instances/{id}/terminate` | 停止並移除機器 |
| POST | `/v1/instances/{id}/schedule-removal` | 設定它何時自行移除 |
| GET / POST / DELETE | `/v1/volumes` | 你的儲存磁碟區：儲存了多少資料、費用多少、掛載在哪裡 |
| GET | `/v1/billing/account` | 餘額、消耗速度，以及餘額何時用完 |
| POST | `/v1/billing/checkout` | 發起銀行卡、Link 或 Apple Pay 付款 |
| POST | `/v1/billing/stop` | 停止所有機器並暫停租用 |
| GET / POST / DELETE | `/v1/tokens` | 列出、建立和撤銷權杖 |
| GET | `/v1/support/cases` | 你的支援工單和我們的答覆 |
| POST | `/mcp` | 面向 AI 代理的 MCP |

## 重試

重試租用時傳送相同的 `idempotency_key`：你拿回的是同一臺機器，絕不會多租一臺。

更多：[全部文件](/zh-tw/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/zh-tw/llms.txt)