# 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` | 面向智能体的 MCP |

## 重试

重试租用时发送相同的 `idempotency_key`：你拿回的是同一台机器，绝不会多租一台。

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