For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 服务器:

响应:


获取你的订单

包含已完成/已过期订单:


创建订单(按需)

响应:


创建一个现货订单

现货订单更便宜,但可能会被更高出价者抢走。你可以设置每天的价格:


自动续租 48 小时

在最大租期(mrl)短于 48 小时的服务器上,只要续租价格不高于你的 auto_renew_max_price 每一天的上限,订单会在每个期限结束时按当时主机的价格续租,并在 48 小时用完后结束。省略 rental_hours 即可一直续租直到你取消。若没有 auto_renew,超过服务器 mrl 的小时数将被拒绝,返回 rental_hours_exceeds_mrl.

响应:


检查订单状态

活动订单包括 pub_cluster (主机名)和 tcp_ports 用于 SSH 访问:

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

更改自动续租

开启续租、更改价格上限,或更改正在运行的按需订单的总小时数。省略的字段会保持其值,并且 "rental_hours": null 会移除小时限制。此请求会让订单持续续租,直到你取消它:

发送 { "order_id": 38, "auto_renew": false } 以停止续租;随后订单将在当前期限结束时终止。在一个期限的最后 60 秒内,该请求会被拒绝,返回 renewal_in_progress;请在订单续租或结束后重试。 my_orders 会在以下字段中显示结果: auto_renew, auto_renew_max_price, rental_hours, rental_end 和 term_end.

读取续租历史

响应 (最新在前,每次续租决策一行,已续租或已拒绝):


取消订单

可选地报告服务器问题:


Python SDK

一个使用 requests 库的轻量级封装。安装方式:

CloreClient 类

完整可运行示例


Node.js 示例

使用原生 fetch API(Node.js 18+):


常见工作流

寻找最便宜的 RTX 4090 并租用


监控我的订单


当价格跌破 X 时自动租用


WebSocket

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


速率限制

端点
限制

大多数端点

1 次请求/秒

create_order

1 次请求/5 秒

set_spot_price (降价)

每 600 秒一次

速率限制响应(代码 5):

最佳实践:

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

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

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

  • 如果需要频繁查询,可将市场数据缓存在本地

Python 辅助函数:


错误处理

每个 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 错误处理示例

JavaScript 错误处理示例


可用的 Docker 镜像

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

镜像
描述

cloreai/ubuntu20.04-jupyter

Ubuntu 20.04 + JupyterLab

cloreai/ubuntu22.04-jupyter

Ubuntu 22.04 + JupyterLab

你也可以使用任何公共 Docker Hub 镜像。要访问 GPU,请使用启用 CUDA 的镜像,例如:


端口转发

创建订单时,请指定要暴露的端口:

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

  • "http" — HTTPS 代理(用于 Jupyter、Web 界面)。每个只能允许一个 HTTP 端口 http_port 字段。

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

通过 SSH 连接:

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

最后更新于

这有帮助吗?