CLI 和 SDK 指南

概述

Clore.ai 提供一个 REST API 使你能够通过程序全面访问 GPU 市场——列出服务器、创建订单、监控部署以及取消租用。

注意： 目前还没有官方 CLI 可执行文件。所有自动化都直接通过 REST API 完成，使用诸如 curl、Python 或 Node.js 等工具。

基础 URL： https://api.clore.ai/v1

响应格式： JSON。每个响应都包含一个 code 字段，用于指示状态。

---

身份验证

从以下位置生成你的 API 密钥： Clore.ai 仪表板:

1. 登录你的账户

2. 导航到 API 设置中的部分

3. 生成并复制你的 API 密钥

请求头格式：

auth: YOUR_API_KEY

⚠️ 重要： auth 请求头是 auth, 而不是 Authorization: Bearer。使用错误格式将返回代码 3 （无效的 API 令牌）。

示例：

curl -H 'auth: YOUR_API_KEY' 'https://api.clore.ai/v1/marketplace'

---

快速开始

列出市场服务器

浏览所有可用的 GPU 服务器：

curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/marketplace'

响应：

{
  "servers": [
    {
      "id": 6,
      "owner": 4,
      "mrl": 73,
      "price": {
        "on_demand": { "bitcoin": 0.00001 },
        "spot": { "bitcoin": 0.000001 }
      },
      "rented": false,
      "specs": {
        "cpu": "Intel Core i9-11900",
        "ram": 62.67,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": { "up": 26.38, "down": 118.42, "cc": "CZ" }
      }
    }
  ],
  "my_servers": [1, 2, 4],
  "code": 0
}

---

获取你的订单

curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders'

包含已完成/已过期的订单：

curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders?return_completed=true'

---

创建订单（按需）

curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "on-demand",
    "ports": {
      "22": "tcp",
      "8888": "http"
    },
    "ssh_password": "YourSSHPassword123",
    "jupyter_token": "YourJupyterToken123"
  }' \
  'https://api.clore.ai/v1/create_order'

响应：

{ "code": 0 }

---

创建抢占式订单

抢占式订单更便宜，但可能会被更高出价覆盖。你设置你的每日价格：

curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "spot",
    "spotprice": 0.000005,
    "ports": {
      "22": "tcp",
      "8888": "http"
    },
    "ssh_password": "YourSSHPassword123"
  }' \
  'https://api.clore.ai/v1/create_order'

---

检查订单状态

curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders'

活跃订单包含 pub_cluster （主机名）和 tcp_ports 用于 SSH 访问：

{
  "id": 38,
  "pub_cluster": ["n1.c1.clorecloud.net", "n2.c1.clorecloud.net"],
  "tcp_ports": ["22:10000"],
  "http_port": "8888",
  "expired": false
}

SSH 登录到你租用的服务器：

ssh [e-mail] -p 10000

---

取消订单

curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "id": 38
  }' \
  'https://api.clore.ai/v1/cancel_order'

可选地报告服务器问题：

curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "id": 38,
    "issue": "GPU was overheating and throttling performance"
  }' \
  'https://api.clore.ai/v1/cancel_order'

---

Python SDK

一个使用 requests 库的轻量封装。使用以下命令安装：

pip install requests

CloreClient 类

import requests
import time

class CloreClient:
    """Clore.ai REST API 的简单 Python SDK。"""
    
    BASE_URL = "https://api.clore.ai/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({"auth": api_key})
    
    def _get(self, endpoint: str, params: dict = None) -> dict:
        url = f"{self.BASE_URL}/{endpoint}"
        response = self.session.get(url, params=params)
        response.raise_for_status()
        data = response.json()
        if data.get("code") != 0:
            raise CloreAPIError(data)
        return data
    
    def _post(self, endpoint: str, body: dict) -> dict:
        url = f"{self.BASE_URL}/{endpoint}"
        self.session.headers.update({"Content-type": "application/json"})
        response = self.session.post(url, json=body)
        response.raise_for_status()
        data = response.json()
        if data.get("code") != 0:
            raise CloreAPIError(data)
        return data
    
    def list_servers(self) -> list:
        """获取市场上所有可用的服务器。"""
        data = self._get("marketplace")
        return data["servers"]
    
    def get_server_details(self, server_id: int) -> dict:
        """获取特定服务器的抢占式市场信息。"""
        data = self._get("spot_marketplace", params={"market": server_id})
        return data["market"]
    
    def create_order(
        self,
        server_id: int,
        image: str,
        order_type: str = "on-demand",
        currency: str = "bitcoin",
        spotprice: float = None,
        ports: dict = None,
        ssh_password: str = None,
        ssh_key: str = None,
        jupyter_token: str = None,
        env: dict = None,
        command: str = None,
    ) -> dict:
        """
        创建按需或抢占式订单。
        
        参数：
            server_id：要租用的服务器 ID
            image：Docker 镜像（例如 'cloreai/ubuntu20.04-jupyter'）
            order_type：'on-demand' 或 'spot'
            currency：'bitcoin'（默认）
            spotprice：抢占式订单必需——以 BTC 计的每日价格
            ports：端口转发，例如 {"22": "tcp", "8888": "http"}
            ssh_password：SSH 密码（仅限字母数字字符）
            ssh_key：SSH 公钥
            jupyter_token：Jupyter Notebook 令牌
            env：环境变量字典
            command：容器启动后要运行的 shell 命令
        """
        if order_type == "spot" and spotprice is None:
            raise ValueError("抢占式订单需要 spotprice")
        
        body = {
            "currency": currency,
            "image": image,
            "renting_server": server_id,
            "type": order_type,
        }
        
        if spotprice is not None:
            body["spotprice"] = spotprice
        if ports:
            body["ports"] = ports
        if ssh_password:
            body["ssh_password"] = ssh_password
        if ssh_key:
            body["ssh_key"] = ssh_key
        if jupyter_token:
            body["jupyter_token"] = jupyter_token
        if env:
            body["env"] = env
        if command:
            body["command"] = command
        
        return self._post("create_order", body)
    
    def get_orders(self, include_completed: bool = False) -> list:
        """获取你活跃的（以及可选的已完成）订单。"""
        params = {"return_completed": "true"} if include_completed else {}
        data = self._get("my_orders", params=params)
        return data["orders"]
    
    def cancel_order(self, order_id: int, issue: str = None) -> dict:
        """取消订单。可选地报告问题。"""
        body = {"id": order_id}
        if issue:
            body["issue"] = issue
        return self._post("cancel_order", body)
    
    def get_wallets(self) -> list:
        """获取你的钱包和余额。"""
        data = self._get("wallets")
        return data["wallets"]
    
    def get_my_servers(self) -> list:
        """获取你提供给市场的服务器。"""
        data = self._get("my_servers")
        return data["servers"]


class CloreAPIError(Exception):
    """当 Clore API 返回非零代码时引发。"""
    
    ERROR_CODES = {
        0: "正常",
        1: "数据库错误",
        2: "无效输入数据",
        3: "无效 API 令牌",
        4: "无效端点",
        5: "超出速率限制（1 请求/秒）",
        6: "错误（请参见 error 字段）",
    }
    
    def __init__(self, response: dict):
        self.code = response.get("code")
        self.error = response.get("error", "")
        message = self.ERROR_CODES.get(self.code, f"未知代码 {self.code}")
        if self.error:
            message = f"{message}: {self.error}"
        super().__init__(f"Clore API 错误 {self.code}: {message}")

完整工作示例

import os
from clore_client import CloreClient, CloreAPIError

# 初始化客户端
client = CloreClient(api_key=os.environ["CLORE_API_KEY"])

# 1. 浏览市场
servers = client.list_servers()
print(f"在市场中找到 {len(servers)} 台服务器")

# 2. 筛选可用的 RTX 4090 服务器
rtx4090_servers = [
    s for s in servers
    if "4090" in s["specs"].get("gpu", "") and not s["rented"]
]

if not rtx4090_servers:
    print("未找到可用的 RTX 4090 服务器")
    exit(1)

# 3. 选择最便宜的一个
cheapest = min(rtx4090_servers, key=lambda s: s["price"]["on_demand"]["bitcoin"])
print(f"最便宜的 RTX 4090：服务器 ID {cheapest['id']}，"
      f"价格 {cheapest['price']['on_demand']['bitcoin']:.8f} BTC/天")

# 4. 创建订单
try:
    client.create_order(
        server_id=cheapest["id"],
        image="cloreai/ubuntu20.04-jupyter",
        order_type="on-demand",
        currency="bitcoin",
        ports={"22": "tcp", "8888": "http"},
        ssh_password="SecurePass123",
        jupyter_token="MyToken123",
    )
    print("订单创建成功！")
except CloreAPIError as e:
    print(f"创建订单失败：{e}")
    exit(1)

# 5. 检查你的订单
orders = client.get_orders()
for order in orders:
    if not order.get("expired"):
        cluster = order.get("pub_cluster", [])
        tcp = order.get("tcp_ports", [])
        print(f"订单 {order['id']}：服务器 {order['si']}")
        if cluster and tcp:
            ssh_port = tcp[0].split(":")[1]
            print(f"  SSH：ssh root@{cluster[0]} -p {ssh_port}")

---

Node.js 示例

使用原生 fetch API（Node.js 18+）：

const BASE_URL = 'https://api.clore.ai/v1';

class CloreClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.defaultHeaders = {
      'auth': apiKey,
    };
  }

  async get(endpoint, params = {}) {
    const url = new URL(`${BASE_URL}/${endpoint}`);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    
    const res = await fetch(url.toString(), {
      headers: this.defaultHeaders,
    });
    
    const data = await res.json();
    if (data.code !== 0) {
      throw new Error(`Clore API 错误 ${data.code}: ${data.error || '未知'}`);
    }
    return data;
  }

  async post(endpoint, body) {
    const res = await fetch(`${BASE_URL}/${endpoint}`, {
      method: 'POST',
      headers: {
        ...this.defaultHeaders,
        'Content-type': 'application/json',
      },
      body: JSON.stringify(body),
    });
    
    const data = await res.json();
    if (data.code !== 0) {
      throw new Error(`Clore API 错误 ${data.code}: ${data.error || '未知'}`);
    }
    return data;
  }

  async listServers() {
    const data = await this.get('marketplace');
    return data.servers;
  }

  async getOrders(includeCompleted = false) {
    const params = includeCompleted ? { return_completed: 'true' } : {};
    const data = await this.get('my_orders', params);
    return data.orders;
  }

  async createOrder({ serverId, image, type = 'on-demand', currency = 'bitcoin', spotprice, ports, sshPassword, jupyterToken, env, command }) {
    const body = {
      currency,
      image,
      renting_server: serverId,
      type,
      ...(spotprice && { spotprice }),
      ...(ports && { ports }),
      ...(sshPassword && { ssh_password: sshPassword }),
      ...(jupyterToken && { jupyter_token: jupyterToken }),
      ...(env && { env }),
      ...(command && { command }),
    };
    return this.post('create_order', body);
  }

  async cancelOrder(orderId, issue = null) {
    const body = { id: orderId };
    if (issue) body.issue = issue;
    return this.post('cancel_order', body);
  }
}

// 使用示例
const client = new CloreClient(process.env.CLORE_API_KEY);

async function main() {
  // 列出市场
  const servers = await client.listServers();
  console.log(`市场中有 ${servers.length} 台服务器`);

  // 查找可用的 RTX 4090 服务器
  const available = servers.filter(
    s => s.specs.gpu.includes('4090') && !s.rented
  );
  console.log(`可用的 RTX 4090 服务器：${available.length} 台`);

  // 获取当前订单
  const orders = await client.getOrders();
  const activeOrders = orders.filter(o => !o.expired);
  console.log(`活跃订单：${activeOrders.length} 个`);

  for (const order of activeOrders) {
    const host = order.pub_cluster?.[0];
    const portMapping = order.tcp_ports?.[0];
    if (host && portMapping) {
      const sshPort = portMapping.split(':')[1];
      console.log(`订单 ${order.id} → ssh root@${host} -p ${sshPort}`);
    }
  }
}

main().catch(console.error);

---

常见工作流

找到最便宜的 RTX 4090 并租用

from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def rent_cheapest_rtx4090(image="cloreai/ubuntu20.04-jupyter", ssh_password="SecurePass123"):
    servers = client.list_servers()
    
    # 过滤：可用的 RTX 4090
    candidates = [
        s for s in servers
        if "4090" in s["specs"].get("gpu", "")
        and not s["rented"]
    ]
    
    if not candidates:
        raise RuntimeError("未找到可用的 RTX 4090 服务器")
    
    # 按按需 BTC 价格排序
    candidates.sort(key=lambda s: s["price"]["on_demand"]["bitcoin"])
    best = candidates[0]
    
    price_btc = best["price"]["on_demand"]["bitcoin"]
    print(f"租用服务器 {best['id']}：{best['specs']['gpu']} @ {price_btc:.8f} BTC/天")
    
    client.create_order(
        server_id=best["id"],
        image=image,
        order_type="on-demand",
        currency="bitcoin",
        ports={"22": "tcp"},
        ssh_password=ssh_password,
    )
    
    print("完成！请查看你的订单以获取 SSH 连接详情。")
    return best["id"]

rent_cheapest_rtx4090()

---

监控我的订单

import time
from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def monitor_orders(poll_interval_seconds=60):
    """轮询订单并打印状态更新。"""
    print(f"监控订单（每 {poll_interval_seconds} 秒轮询一次）。按 Ctrl+C 停止。\n")
    
    while True:
        orders = client.get_orders(include_completed=False)
        active = [o for o in orders if not o.get("expired")]
        
        print(f"--- {len(active)} 个活跃订单 ---")
        for order in active:
            cluster = order.get("pub_cluster", [])
            tcp = order.get("tcp_ports", [])
            spend = order.get("spend", 0)
            
            ssh_info = ""
            if cluster and tcp:
                port = tcp[0].split(":")[1]
                ssh_info = f" | SSH: {cluster[0]}:{port}"
            
            print(f"  订单 {order['id']}：服务器 {order['si']}"
                  f" | 已花费 {spend:.8f} BTC{ssh_info}")
        
        if not active:
            print("  当前没有活跃订单。")
        
        print()
        time.sleep(poll_interval_seconds)

monitor_orders()

---

当价格跌破 X 时自动租用

import time
from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def auto_rent_on_price_drop(
    gpu_model: str = "RTX 4090",
    max_price_btc: float = 0.00015,
    image: str = "cloreai/ubuntu20.04-jupyter",
    ssh_password: str = "SecurePass123",
    check_interval_seconds: int = 120,
):
    """
    监控市场，当价格低于阈值时自动租用 GPU。
    
    参数：
        gpu_model：要搜索的 GPU 名称（不区分大小写）
        max_price_btc：可接受的每日最高价格（BTC）
        image：要部署的 Docker 镜像
        ssh_password：容器的 SSH 密码
        check_interval_seconds：检查频率（注意速率限制！）
    """
    print(f"正在监控 {gpu_model}，目标价格 ≤ {max_price_btc:.8f} BTC/天...")
    
    while True:
        servers = client.list_servers()
        
        for server in servers:
            gpu = server["specs"].get("gpu", "")
            if gpu_model.lower() not in gpu.lower():
                continue
            if server["rented"]:
                continue
            
            price = server["price"]["on_demand"]["bitcoin"]
            if price <= max_price_btc:
                print(f"🎯 找到匹配项！服务器 {server['id']}：{gpu} @ {price:.8f} BTC/天")
                
                try:
                    client.create_order(
                        server_id=server["id"],
                        image=image,
                        order_type="on-demand",
                        currency="bitcoin",
                        ports={"22": "tcp"},
                        ssh_password=ssh_password,
                        required_price=price,  # 锁定此价格
                    )
                    print(f"✅ 已为服务器 {server['id']} 创建订单！")
                    return server["id"]
                except Exception as e:
                    print(f"创建订单失败：{e}。将重试……")
        
        print(f"尚未找到匹配项。将在 {check_interval_seconds}s 后再次检查……")
        time.sleep(check_interval_seconds)

auto_rent_on_price_drop(gpu_model="4090", max_price_btc=0.00012)

---

WebSocket

Clore.ai REST API 目前尚未提供 WebSocket 端点。对于实时监控，请使用合理间隔的轮询（见下方速率限制）。

---

速率限制

端点	限制
大多数端点	每秒 1 次请求
create_order	每 5 秒 1 次请求
set_spot_price （降价）	每隔 600 秒

速率限制响应（代码 5）：

{ "code": 5 }

最佳实践：

• 在 time.sleep(1) 连续 API 调用之间

• 对于 create_order，请求之间至少等待 5 秒

• 监控循环使用 60 秒以上的轮询间隔

• 如果需要频繁查询，请在本地缓存市场数据

Python 辅助函数：

import time

def safe_api_call(fn, *args, delay=1.1, **kwargs):
    """带速率限制安全保护的 API 调用包装。"""
    result = fn(*args, **kwargs)
    time.sleep(delay)
    return result

---

错误处理

每个 API 响应都包含一个 code 字段。其值为 0 表示成功。

错误代码

代码	含义	操作
0	成功	—
1	数据库错误	延迟后重试
2	输入数据无效	检查你的请求体/参数
3	API 令牌无效	在控制面板中验证你的 API 密钥
4	端点无效	检查端点 URL
5	超出速率限制（1 次请求/秒）	在请求之间添加延迟
6	应用错误（参见 错误 字段）	查看 错误 字段了解详情

代码 6 子错误

错误 值	含义
exceeded_max_step	现货价格降幅过大；检查 max_step 字段
can_lower_every_600_seconds	在再次降低现货价格前必须等待；检查 time_to_lowering

Python 错误处理示例

from clore_client import CloreClient, CloreAPIError
import time

client = CloreClient(api_key="YOUR_API_KEY")

def create_order_with_retry(server_id, image, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.create_order(
                server_id=server_id,
                image=image,
                order_type="on-demand",
                currency="bitcoin",
                ports={"22": "tcp"},
                ssh_password="SecurePass123",
            )
        except CloreAPIError as e:
            if e.code == 5:  # 速率限制
                print(f"已触发速率限制。等待 5 秒……（第 {attempt+1}/{max_retries} 次尝试）")
                time.sleep(5)
            elif e.code == 3:  # API 密钥错误
                print("API 密钥无效！请检查你的 CLORE_API_KEY。")
                raise
            elif e.code == 2:  # 输入错误
                print(f"无效请求：{e}")
                raise
            else:
                print(f"API 错误：{e}。3 秒后重试……")
                time.sleep(3)
    
    raise RuntimeError(f"在 {max_retries} 次尝试后失败")

JavaScript 错误处理示例

async function createOrderWithRetry(client, serverConfig, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.createOrder(serverConfig);
    } catch (err) {
      const code = parseInt(err.message.match(/error (\d+)/)?.[1]);
      
      if (code === 5) {
        console.log(`已触发速率限制。等待 5 秒……（第 ${attempt + 1}/${maxRetries} 次尝试）`);
        await new Promise(r => setTimeout(r, 5000));
      } else if (code === 3) {
        throw new Error('API 密钥无效');
      } else {
        console.log(`API 错误：${err.message}。3 秒后重试……`);
        await new Promise(r => setTimeout(r, 3000));
      }
    }
  }
  throw new Error(`在 ${maxRetries} 次尝试后失败`);
}

---

可用的 Docker 镜像

Clore.ai 提供针对 GPU 工作负载优化的预构建镜像：

镜像	描述
cloreai/ubuntu20.04-jupyter	Ubuntu 20.04 + JupyterLab
cloreai/ubuntu22.04-jupyter	Ubuntu 22.04 + JupyterLab

你也可以使用任何公开的 Docker Hub 镜像。若要访问 GPU，请使用启用 CUDA 的镜像，例如：

nvidia/cuda:12.1.0-devel-ubuntu22.04

---

端口转发

创建订单时，请指定要暴露的端口：

{
  "ports": {
    "22": "tcp",
    "8888": "http",
    "6006": "http"
  }
}

• "tcp" — 直接 TCP 端口转发（用于 SSH、自定义服务器）

• "http" — HTTPS 代理（用于 Jupyter、Web 界面）。每个 http_port 字段仅允许一个 HTTP 端口。

订单创建后，连接详情会显示在 my_orders:

{
  "pub_cluster": ["n1.c1.clorecloud.net", "n2.c1.clorecloud.net"],
  "tcp_ports": ["22:10000"],
  "http_port": "8888"
}

通过 SSH 连接：

ssh [e-mail] -p 10000

通过浏览器访问 Jupyter： https://n1.c1.clorecloud.net （使用 http_port)