> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/mian-xiang-zhu-ji-fang/api.md).

# API

> 💡 **Python 开发者：** 请使用官方 [clore-ai Python SDK](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/kai-fa-zhe/python-sdk.md) ，而不是直接调用 API。它会自动处理身份验证、速率限制、重试和错误处理。
>
> **快速开始：** `pip install clore-ai` — 参见 [Python SDK 文档](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/kai-fa-zhe/python-sdk.md) 和 [CLI 参考](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/kai-fa-zhe/cli-guide.md).

> 🧭 更喜欢可浏览的参考？请在以下地址打开交互式 API 文档： [clore.ai/api-docs](https://clore.ai/api-docs)。本页面所有端点的基础 URL： `https://api.clore.ai/v1/`.

<div data-full-width="true"><figure><img src="https://1308073318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbyNlC5NV8aIpXnc76G7w%2Fuploads%2FoEhopGeayaKnbuDjgTEs%2FCLORE%20Docs%20API%20Page.png?alt=media&amp;token=a0adf6bb-1fde-4f1b-8236-dff2563ffbfd" alt=""><figcaption></figcaption></figure></div>

### 简介 <a href="#introduction" id="introduction"></a>

[CLORE.AI](http://clore.ai/) API 可用于自动化将您的工作负载部署到 [CLORE.AI](http://clore.ai/)

首先，您需要获取一个 API 密钥\
![alt text](https://clore.ai/assets/html/api-export1.png)\
![alt text](https://clore.ai/assets/html/api-export2.png)

***

### API 响应 <a href="#api-responses" id="api-responses"></a>

响应以 JSON 格式返回，可能包含不同字段

始终返回的字段是 code，用于表示状态

**code 字段**

| code | 描述           |
| ---- | ------------ |
| `0`  | 正常           |
| `1`  | 数据库错误        |
| `2`  | 输入数据无效       |
| `3`  | API 令牌无效     |
| `4`  | 无效端点         |
| `5`  | 超过 1 请求/秒限制  |
| `6`  | 错误位于 `错误` 字段 |

***

### 端点 <a href="#endpoints" id="endpoints"></a>

#### 1. `钱包` <a href="#id-1-wallets" id="id-1-wallets"></a>

**关于**

返回钱包和余额

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**输出**

| 字段     | 类型      | 描述   |
| ------ | ------- | ---- |
| `code` | `int`   | 状态码  |
| `钱包`   | `[]字符串` | 钱包数组 |

**示例**

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/wallets'
```

**输出：**

```
{
  "wallets": [
    {
      "name": "bitcoin",
      "deposit": "tb1q6erw7v02t7hakgmlcl4wfnlykzqj05alndruwr",
      "balance": 0.00153176,
      "withdrawal_fee": 0.0001
    }
  ],
  "code": 0
}
```

#### 2. `my_servers` <a href="#id-2-my_servers" id="id-2-my_servers"></a>

**关于**

返回您正在提供给 [clore.ai](http://clore.ai/) 市场

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**输出**

| 字段                                    | 类型      | 描述                                                                                                                         |
| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `code`                                | `int`   | 状态码                                                                                                                        |
| `上限`                                  | `int`   | 您最多可以拥有的服务器数量                                                                                                              |
| `服务器`                                 | `[]字符串` | 服务器数组                                                                                                                      |
| `servers[x].name`                     | `字符串`   | 用户选择的服务器名称                                                                                                                 |
| `servers[x].connected`                | `字符串`   | 服务器是否曾连接过 [clore.ai](http://clore.ai/)                                                                                     |
| `servers[x].visibility`               | `字符串`   | 市场可见性                                                                                                                      |
| `servers[x].pricing`                  | `[]字符串` | 按需每日报价                                                                                                                     |
| `servers[x].online`                   | `bool`  | 服务器是否在线                                                                                                                    |
| `servers[x].min_spot_pricing`         | `[]字符串` | 现货市场最低每日报价                                                                                                                 |
| `servers[x].auto_renew_allowed`       | `bool`  | 租户在此服务器上的按需订单在达到最长租用时长后，是否可以按您当前的价格续租。 `true` 当您从未设置过时。正在移除的服务器上不存在。可通过 [`set_server_settings`](#id-7-set_server_settings) |
| `servers[x].init_token`               | `字符串`   | 机器注册令牌，仅在机器初始化之前返回—— **请将其视为凭证**，它会将机器注册到您的账户                                                                              |
| `servers[x].specs`                    | `[]字符串` | 服务器规格                                                                                                                      |
| `servers[x].remaining_time`           | `int`   | 最近有效订单的租用结束时间（毫秒级 Unix 时间戳）                                                                                                |
| `servers[x].rental_state`             | `字符串`   | GPU 总租用状态： `无`, `部分`，或 `全部`                                                                                                |
| `servers[x].rented_gpus`              | `int`   | 当前在有效订单中租用的 GPU                                                                                                            |
| `servers[x].total_gpus`               | `int`   | 服务器上的 GPU 总数                                                                                                               |
| `servers[x].rented_price_by_currency` | `对象`    | 按货币键统计的有效订单价格总和                                                                                                            |
| `servers[x].update_channel`           | `字符串`   | 托管代理更新通道： `stable` 或 `beta`                                                                                                |
| `servers[x].requested_channel`        | `字符串`   | 由网页界面请求的通道切换（仅在请求时出现）                                                                                                      |
| `servers[x].target_backend_version`   | `int`   | 当前通道所指向的后端版本                                                                                                               |

> 租用状态字段（`remaining_time`, `rental_state`, `rented_gpus`, `total_gpus`, `rented_price_by_currency`）仅在服务器有有效订单时存在。

**示例**

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/my_servers'
```

**输出：**

```
{
  "servers": [
    {
      "name": "Michael",
      "connected": false,
      "visibility": "hidden",
      "pricing": { "bitcoin": 0, "usd": 0 },
      "online": false,
      "min_spot_pricing": { "bitcoin": 0, "usd": 0 },
      "auto_renew_allowed": true,
      "init_token": "qnwVIMsZPjUWS7jw6gAbTOeoGQNgTH9XVxJaiCEbG0OlmfjF"
    },
    {
      "name": "Jan Vykydal",
      "connected": true,
      "visibility": "public",
      "pricing": { "bitcoin": 0.00010337, "usd": 0 },
      "online": false,
      "min_spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
      "auto_renew_allowed": true,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "Intel Core i9-11900",
        "cpus": "8/16",
        "ram": 64,
        "disk": "NVMe 512GB",
        "disk_speed": 2000,
        "gpu": "1x GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "down":119.61,
          "up":25.24
        }
      }
    }
  ],
  "limit": 16,
  "code": 0
}
```

USD 值在 `pricing` 对象中反映的是主机启用的基于 USD 的定价模式。

#### 3. `server_config` <a href="#id-3-server_config" id="id-3-server_config"></a>

**关于**

获取指定服务器的配置

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段            | 类型    | 必填 | 描述    |
| ------------- | ----- | -- | ----- |
| `server_name` | `字符串` | 是  | 服务器名称 |

**输出**

| 字段                          | 类型            | 描述                                                                           |
| --------------------------- | ------------- | ---------------------------------------------------------------------------- |
| `code`                      | `int`         | 状态码                                                                          |
| `creation_completed`        | `bool`        | 服务器创建是否完成                                                                    |
| `config`                    | `[]字符串`       | 服务器配置                                                                        |
| `config.name`               | `字符串`         | 用户选择的服务器名称                                                                   |
| `config.connected`          | `bool`        | 服务器是否曾连接过 [clore.ai](http://clore.ai/)                                       |
| `config.visibility`         | `字符串`         | 市场可见性                                                                        |
| `config.pricing`            | `[]字符串`       | 按需每日报价                                                                       |
| `config.spot_pricing`       | `[]字符串`       | 现货市场最低每日报价                                                                   |
| `config.mrl`                | `int`         | 最长租用时长（小时）                                                                   |
| `config.auto_renew_allowed` | `bool`        | 租户在此服务器上的按需订单在达到时是否可以按主机当前价格续租 `mrl`. `true` 当您从未设置过时                        |
| `config.online`             | `bool`        | 服务器是否在线                                                                      |
| `config.initialized`        | `bool`        | 服务器是否曾连接过 [clore.ai](http://clore.ai/)                                       |
| `config.id`                 | `int`         | 唯一服务器 ID                                                                     |
| `config.rental_status`      | `int`         | 0 - 未租用 \| 1 - 在现货市场租用 \| 2 - 按需租用 \| 3 - 固定 USD 租用                          |
| `config.specs`              | `[]字符串`       | 服务器规格                                                                        |
| `config.background_job`     | `对象`          | 未被租用时的后台任务： `image`, `command`, `env`, `更新次数`                                |
| `config.autoprice`          | `对象` \| `字符串` | 按货币自动定价配置（旧版字符串值 `"pow"` / `"usd"` 也会出现）                                     |
| `config.usd_pricing`        | `对象`          | USD 价格目标——仅在启用 USD 自动定价时存在                                                   |
| `config.tenants`            | `[]对象`        | 服务器上的有效订单： `rental_type`, `currency`, `price`, `remaining_time`, `gpu_count` |

> `server_config` 也会返回与 `my_servers`: `remaining_time`, `rental_state`, `rented_gpus`, `total_gpus`, `rented_price_by_currency`, `update_channel`, `requested_channel`, `target_backend_version`相同的租用状态和更新通道字段。在这两个端点中，租用状态字段仅在服务器有有效订单时存在。

**示例**

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "server_name":"Jan Vykydal"
}' 'https://api.clore.ai/v1/server_config'
```

**输出：**

```
{
  "config": {
    "name": "Jan Vykydal",
    "connected": true,
    "visibility": "public",
    "pricing": { "bitcoin": 0.00010337, "usd": 0 },
    "spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
    "mrl": 72,
    "auto_renew_allowed": true,
    "online": false,
    "initialized": true,
    "id": 4,
    "rental_status": 0,
    "specs": {
      "mb": "Z590 GAMING X",
      "cpu": "Intel Core i9-11900",
      "cpus": "8/16",
      "ram": 64,
      "disk": "NVMe 512GB",
      "disk_speed": 2000,
      "gpu": "1x GeForce GTX 1080 Ti",
      "gpuram": 11,
      "net": {
        "down":119.61,
        "up":25.24
      }
    },
    "background_job": {
      "times_updated": 1,
      "image": "cloreai/ubuntu20.04-jupyter",
      "command": "",
      "env": []
    }
  },
  "creation_completed": true,
  "code": 0
}
```

USD 值在 `pricing` 对象中反映的是主机启用的基于 USD 的定价模式。

#### 4. `市场` <a href="#id-4-marketplace" id="id-4-marketplace"></a>

**关于**

获取市场

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**输出**

| 字段                              | 类型             | 描述                                                                                                                                             |
| ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                          | `int`          | 状态码                                                                                                                                            |
| `my_servers`                    | `[]字符串`        | 您正在向其提供服务的服务器 ID 数组 [clore.ai](http://clore.ai/) （不能被租用）                                                                                       |
| `服务器`                           | `[]字符串`        | 市场上的公开服务器数组                                                                                                                                    |
| `servers[x].id`                 | `int`          | 唯一服务器 ID                                                                                                                                       |
| `servers[x].owner`              | `int`          | 唯一所有者 ID                                                                                                                                       |
| `servers[x].mrl`                | `int`          | 最长租用时长，单位为小时。当服务器允许自动续租时，这也是重新定价周期：续租订单每次达到这个时长时都会采用主机当前价格                                                                                     |
| `servers[x].auto_renew_allowed` | `bool`         | 主机是否允许此服务器自动续租。 `true` 当主机从未设置过时。当 `false`, `create_order` 使用 `auto_renew: true` 将被拒绝，并返回 `auto_renew_not_allowed`，且 `rental_hours` 不能超过 `mrl` |
| `servers[x].price.on_demand`    | `[]字符串`        | 按需每日报价                                                                                                                                         |
| `servers[x].price.spot`         | `[]字符串`        | 现货市场最低每日报价                                                                                                                                     |
| `servers[x].rented`             | `bool`         | 服务器是否按需租用                                                                                                                                      |
| `servers[x].specs`              | `[]字符串`        | 服务器规格                                                                                                                                          |
| `servers[x].partial_gpu_rental` | `对象` \| `bool` | `false` 在不支持部分租用时为该值，否则为 `{ total_gpus, available_gpus, free_indices }`                                                                        |

> `price.on_demand` 和 `price.spot` 仅包含每台服务器实际接受的货币——某种货币没有价格的服务器不能用该货币租用。
>
> 列表是缓存快照，因此对服务器的 `mrl` 或 `auto_renew_allowed` 更改可能需要几分钟才会显示在这里。

**示例**

获取市场

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' '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,
      "auto_renew_allowed": true,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 0,
        "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
}
```

#### 5. `my_orders` <a href="#id-5-my_orders" id="id-5-my_orders"></a>

**关于**

获取您的订单

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**查询字符串**

| 字段                 | 类型     | 必填 | 描述           |
| ------------------ | ------ | -- | ------------ |
| `return_completed` | `bool` | 否  | 返回已完成（已过期）订单 |

**输出**

| 字段                               | 类型      | 描述                                                                                                                                                                                                                                                                                                                   |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                           | `int`   | 状态码                                                                                                                                                                                                                                                                                                                  |
| `上限`                             | `int`   | 当前始终为 999999                                                                                                                                                                                                                                                                                                         |
| `订单`                             | `[]字符串` | 订单数组                                                                                                                                                                                                                                                                                                                 |
| `orders[x].id`                   | `int`   | 唯一订单 ID                                                                                                                                                                                                                                                                                                              |
| `orders[x].creation_fee`         | `float` | 创建费支付给 [clore.ai](http://clore.ai/)                                                                                                                                                                                                                                                                                  |
| `orders[x].price`                | `float` | 订单每日价格（费用）                                                                                                                                                                                                                                                                                                           |
| `orders[x].mrl`                  | `int`   | 从创建到当前租期结束的秒数。续租会把新租期追加到它后面，因此 `ct + mrl` 始终是当前到期时间                                                                                                                                                                                                                                                                  |
| `orders[x].image`                | `字符串`   | 使用的 Docker 镜像                                                                                                                                                                                                                                                                                                        |
| `orders[x].currency`             | `字符串`   | 用于计费的货币                                                                                                                                                                                                                                                                                                              |
| `orders[x].spend`                | `float` | 截至目前实际扣除的金额：累计租用价值加上租户基础费用（PoH 减免后）以及任何额外费用；不包括一次性创建费用                                                                                                                                                                                                                                                               |
| `orders[x].gpu_count`            | `int`   | 订单占用的 GPU 数量（按需订单；除非是部分租用，否则等于设备的 GPU 总数）                                                                                                                                                                                                                                                                            |
| `orders[x].ct`                   | `int`   | 创建时间（UNIX 时间）                                                                                                                                                                                                                                                                                                        |
| `orders[x].p`                    | `int`   | 当前使用的代理集群                                                                                                                                                                                                                                                                                                            |
| `orders[x].specs`                | `[]字符串` | 服务器规格                                                                                                                                                                                                                                                                                                                |
| `orders[x].si`                   | `int`   | 唯一服务器 ID                                                                                                                                                                                                                                                                                                             |
| `orders[x].pub_cluster`          | `[]字符串` | 带端口转发的公共端点                                                                                                                                                                                                                                                                                                           |
| `orders[x].tcp_ports`            | `[]字符串` | TCP 端口转发                                                                                                                                                                                                                                                                                                             |
| `orders[x].http_port`            | `字符串`   | 通过 HTTPS 代理转发的容器端口                                                                                                                                                                                                                                                                                                   |
| `orders[x].spot`                 | `bool`  | 表示这是现货订单                                                                                                                                                                                                                                                                                                             |
| `orders[x].expired`              | `bool`  | 表示订单已过期                                                                                                                                                                                                                                                                                                              |
| `orders[x].rental_hours`         | `int`   | 您请求的小时数，从创建时间开始计算（仅限按需订单）。如果未请求上限，则不会出现：此时订单会在主机的最长租用时长处结束，除非 `auto_renew` 已开启，此时它会一直运行直到您取消                                                                                                                                                                                                                         |
| `orders[x].rental_end`           | `int`   | 请求的小时数用尽时的 UNIX 时间；如果未请求上限则不会出现                                                                                                                                                                                                                                                                                      |
| `orders[x].term_start`           | `int`   | 当前租期开始时的 UNIX 时间（创建时，或上次续租时）                                                                                                                                                                                                                                                                                         |
| `orders[x].term_end`             | `int`   | 当前租期结束时的 UNIX 时间；始终 `ct + mrl`。对现货订单以及在自动续租功能上线前创建且之后从未编辑过的按需订单不存在                                                                                                                                                                                                                                                   |
| `orders[x].term_mrl`             | `int`   | 当前租期开始时主机的最长租用时长，单位为秒。 [`set_order_auto_renew`](#id-16-set_order_auto_renew) 可以将当前租期延长至 `term_start + term_mrl`                                                                                                                                                                                                      |
| `orders[x].last_renewal_at`      | `int`   | 最后一次续租应用时的 UNIX 时间；第一次续租之前不存在                                                                                                                                                                                                                                                                                        |
| `orders[x].auto_renew`           | `bool`  | 当当前租期结束时，订单是否按主机当前价格续租。设置为 `false` 当续租被拒绝时。对未启用自动续租且之后从未编辑过的订单不存在                                                                                                                                                                                                                                                    |
| `orders[x].auto_renew_max_price` | `float` | 您为续租设置的每日价格上限，以该订单的货币计价。当主机价格高于此值时，续租会被拒绝                                                                                                                                                                                                                                                                            |
| `orders[x].renewals_count`       | `int`   | 截至目前已应用的续租次数；第一次续租之前不存在                                                                                                                                                                                                                                                                                              |
| `orders[x].pending_renewal`      | `对象`    | 当已安排在当前租期结束时进行续租时存在： `price` (`float`，下一个租期的每日价格）以及 `term_seconds` (`int`，下一个租期的时长（秒））                                                                                                                                                                                                                               |
| `orders[x].auto_renew_declined`  | `对象`    | 在续费被拒绝后显示： `原因` 和 `于` （决策的 UNIX 时间）。订单会以当前期限结束。 `原因` 属于以下之一 `price_above_cap` （主机新的每日价格高于 `auto_renew_max_price`), `server_unlisted` （服务器被隐藏或正在移除，不再接受订单的货币，或其中没有价格，或者不再通过新订单必须通过的健康检查）， `host_disallowed` （主机关闭了自动续费）， `server_reserved` （服务器已保留给另一位租户）或 `insufficient_balance` （在支付到期限结束为止的费用后，你的余额在新价格下只能支撑不到一小时） |

> 自自动续费上线以来创建的每个按需订单都带有 `term_start`, `term_end` 和 `term_mrl`。其他续费字段仅在适用时出现： `rental_hours` 和 `rental_end` 在请求了小时数时， `auto_renew` 和 `auto_renew_max_price` 在创建时请求了自动续费或通过以下方式设置时， [`set_order_auto_renew`](#id-16-set_order_auto_renew)，且 `renewals_count` 和 `last_renewal_at` 在第一次续费后。参见 [租赁时长与自动续订](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/mian-xiang-zu-ke/order-management.md#rental-length-and-auto-renewal).

**输入：**

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

下面的第一个订单是一个按需订单，运行在一台最长租赁时长为 73 小时（`mrl` 262800 秒）的服务器上，创建时带有 `rental_hours: 120` 并开启了自动续费，且仍处于其第一个期限内。第二个是一个已过期的现货订单。

**输出：**

```
{
  "orders": [
    {
      "id": 38,
      "creation_fee": 3e-7,
      "price": 0.00001,
      "mrl": 262800,
      "image": "cloreai/ubuntu20.04-jupyter",
      "currency": "bitcoin",
      "spend": 6.944444444444445e-9,
      "ct": 1667401396,
      "p": 1,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 2000,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "up": 26.38,
          "down": 118.42
        }
      },
      "si": 6,
      "pub_cluster": [ "n1.c1.clorecloud.net", "n2.c1.clorecloud.net" ],
      "tcp_ports": [ "22:10000" ],
      "http_port": "8888",
      "ssh_auth": "password",
      "rental_hours": 120,
      "rental_end": 1667833396,
      "term_start": 1667401396,
      "term_end": 1667664196,
      "term_mrl": 262800,
      "auto_renew_max_price": 0.0000125,
      "auto_renew": true
    },{
      "id": 36,
      "creation_fee": 1e-7,
      "price": 0.00001,
      "mrl": 262800,
      "image": "cloreai/ubuntu20.04-jupyter",
      "currency": "bitcoin",
      "spend": 1.3888888888888888e-7,
      "ct": 1667248597,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 2000,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "up": 26.38,
          "down": 118.42
        }
      },
      "si": 6,
      "spot": true,
      "ssh_auth": "password",
      "expired": true,
      "tcp_ports": []
    }
  ],
  "limit": 999999,
  "code": 0
}
```

#### 6. `spot_marketplace` <a href="#id-6-spot_marketplace" id="id-6-spot_marketplace"></a>

**关于**

获取特定服务器的现货市场

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**查询字符串**

| 字段   | 类型    | 必填 | 描述       |
| ---- | ----- | -- | -------- |
| `市场` | `int` | 是  | 唯一服务器 ID |

**输出**

| 字段                             | 类型      | 描述                |
| ------------------------------ | ------- | ----------------- |
| `code`                         | `int`   | 状态码               |
| `存在`                           | `bool`  | 验证市场是否存在          |
| `市场`                           | `对象`    | 市场                |
| `market.offers`                | `数组`    | 该服务器的租赁报价         |
| `market.offers[x].offer_id`    | `int`   | 唯一报价 ID           |
| `market.offers[x].bid`         | `float` | 报价的每日价格（以报价所用货币计） |
| `market.offers[x].currency`    | `字符串`   | 报价所用货币            |
| `market.offers[x].active`      | `bool`  | 此报价当前正在使用         |
| `market.offers[x].my`          | `bool`  | 此报价属于我            |
| `market.server`                | `对象`    | 服务器信息             |
| `market.server.min_pricing`    | `对象`    | 每种可接受货币的最低每日报价    |
| `market.server.mrl`            | `int`   | 最长租赁时长为 **小时**    |
| `market.server.visibility`     | `字符串`   | 只有在可见性为公开时才能创建报价  |
| `market.server.online`         | `bool`  | 服务器在线             |
| `market.currency_rates_in_usd` | `对象`    | 用于比较不同货币报价的实时美元汇率 |

> 报价可以使用服务器接受的任何货币；竞争报价会按其 **美元价值** （使用 `currency_rates_in_usd`），而不是面值。
>
> ⚠️ **2026 年 8 月更改：** `market.server.mrl` 现在以 **小时** 返回（之前是秒）。原本读作 `262800` 现在读作 `73`.

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/spot_marketplace?market=6'
```

**输出：**

```
{
  "market": {
    "offers": [
      {
        "offer_id": 39,
        "bid": 0.0000042,
        "active": true,
        "my": true,
        "currency": "bitcoin"
      }
    ],
    "server": {
      "min_pricing": {
        "bitcoin": 0.000001
      },
      "mrl": 73,
      "visibility": "public",
      "online": true
    },
    "currency_rates_in_usd": {
      "bitcoin": 110000,
      "CLORE-Blockchain": 0.0045,
      "USD-Blockchain": 1
    }
  },
  "exists": true,
  "code": 0
}
```

#### 7. `set_server_settings` <a href="#id-7-set_server_settings" id="id-7-set_server_settings"></a>

**关于**

配置你在上提供的服务器设置 [clore.ai](http://clore.ai/) 市场

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段                           | 类型      | 必填  | 描述                                                                                                     |
| ---------------------------- | ------- | --- | ------------------------------------------------------------------------------------------------------ |
| `name`                       | `字符串`   | 是   | 用户选择的服务器名称                                                                                             |
| `可用性`                        | `bool`  | 是   | 服务器是否可出租                                                                                               |
| `mrl`                        | `int`   | 是   | 服务器最长租赁时长（以 **小时** （6 到 3000）                                                                          |
| `bitcoin_on_demand`          | `float` | 是   | BTC 按日按需价格                                                                                             |
| `bitcoin_spot`               | `float` | 是   | BTC 按日最低现货价格                                                                                           |
| `CLORE-Blockchain_on_demand` | `float` | 否   | CLORE 按日按需价格                                                                                           |
| `CLORE-Blockchain_spot`      | `float` | 否   | CLORE 按日最低现货价格                                                                                         |
| `USD-Blockchain_on_demand`   | `float` | 否   | USD 按日按需价格                                                                                             |
| `USD-Blockchain_spot`        | `float` | 否   | USD 按日最低现货价格                                                                                           |
| `enabled-bitcoin`            | `bool`  | 否\* | 接受此服务器的比特币                                                                                             |
| `enabled-CLORE-Blockchain`   | `bool`  | 否\* | 接受此服务器的 CLORE                                                                                          |
| `enabled-USD-Blockchain`     | `bool`  | 否\* | 接受此服务器的美元稳定币                                                                                           |
| `自动定价`                       | `对象`    | 否   | 按货币自动定价：设置一个货币键（`bitcoin`, `CLORE-Blockchain`）为 `"usd"` 用于基于美元的自动定价，或 `false` 用于固定定价                   |
| `usd_pricing`                | `对象`    | 否   | 按货币设置的美元价格目标，例如 `{ "bitcoin": { "on_demand": 10, "spot": 5 } }` ——仅用于以下货币 `自动定价` 设为 `"usd"`            |
| `auto_renew_allowed`         | `bool`  | 否   | 允许租户的按需订单在达到时按你当前的价格续费 `mrl`。省略它可保留已存设置；从未设置过它的服务器允许续费。除此之外的值 `true` 或 `false` 会被拒绝，代码为 `2` （HTTP 400） |

> \* **可接受货币列表会在每次调用时根据 `enabled-*` 标志重建。** 没有其 `enabled-<currency>: true` 标志（或没有有效价格）的货币会从服务器的可接受货币中移除——省略所有标志会使服务器无法以任何货币出租。请始终为每种你想继续接受的货币发送 `enabled-<currency>: true` 。
>
> 每日价格按货币设有上限：0.000001–0.1 BTC、0.1–5,000,000 CLORE、0.1–10,000 USD。
>
> 当某种货币按 USD 自动定价时，其列出的加密货币价格会根据 `usd_pricing` 按实时汇率得出（大约每 10 分钟重新计算一次），而且任何 `<currency>_on_demand` / `<currency>_spot` 为其发送的值都会被忽略。 `usd_pricing` 这些目标值是按整个服务器的美元/天数计算，并按 USD 范围（0.1 到 10,000）验证；超出范围的值会被截到最近的边界。
>
> 当 `auto_renew_allowed` 开启时（默认）， `mrl` 也是你的重新定价周期：当租户选择了自动续费的订单每次到达 `mrl`时，会按那一刻的价格续费。将其设为 `false` 绝不会结束正在运行的租赁：服务器上的每个订单都会完成当前期限，其续费会被拒绝，错误为 `host_disallowed`.

**输出**

| 字段     | 类型    | 描述  |
| ------ | ----- | --- |
| `code` | `int` | 状态码 |

**示例**

**输入：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "name": "Jan Vykydal",
    "availability":true,
    "mrl":96,
    "enabled-bitcoin":true,
    "bitcoin_on_demand":0.0001,
    "bitcoin_spot":0.00000113
}' 'https://api.clore.ai/v1/set_server_settings'
```

**输出：**

```
{
  "code": 0
}
```

#### 8. `set_spot_price` <a href="#id-8-set_spot_price" id="id-8-set_spot_price"></a>

**关于**

设置你在 SPOT 市场报价的每日价格

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段         | 类型      | 必填 | 描述       |
| ---------- | ------- | -- | -------- |
| `order_id` | `int`   | 是  | 唯一报价 ID  |
| `期望价格`     | `float` | 是  | 你报价的每日价格 |

> **低于服务器当前现货下限的价格** 会被拒绝，并返回当前最低价：
>
> ```
> { "error": "amount_too_low", "min_price": 0.0000012, "code": 6 }
> ```
>
> **提价幅度必须至少比你当前报价和服务器同币种最高报价都高 1%** （按该货币精度向上取整，并受价格上限限制）。更小的提价会被拒绝，并返回最低可接受价格：
>
> ```
> { "error": "below_min_raise_step", "min_price": 0.00000425, "code": 6 }
> ```

**示例**

我们来尝试更新现货市场价格

**输入 1（降价幅度过大）：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000200
}' 'https://api.clore.ai/v1/set_spot_price'
```

**可能的输出 1（降价幅度过大）：**\
你可以将现货市场报价最多下调 0.00000100 ₿

| 字段         | 类型      | 描述              |
| ---------- | ------- | --------------- |
| `code`     | `int`   | 状态码             |
| `错误`       | `字符串`   | 错误描述字段          |
| `max_step` | `float` | 你当前可以下调价格的最低可能值 |

```
{
    "error":"exceeded_max_step",
    "max_step":0.0000032,
    "code":6
}
```

**输入 2（有效的降价幅度）：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000320
}' 'https://api.clore.ai/v1/set_spot_price'
```

**可能的输出 2（有效的降价幅度）：**

```
{
    "code": 0
}
```

**输入 3（在发送输入 2 后进一步降价）：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000220
}' 'https://api.clore.ai/v1/set_spot_price
```

**可能的输出 3（在发送输入 2 后进一步降价）：**\
你每 600 秒只能下调一次现货价格

| 字段                 | 类型      | 描述                 |
| ------------------ | ------- | ------------------ |
| `code`             | `int`   | 状态码                |
| `错误`               | `字符串`   | 错误描述字段             |
| `time_to_lowering` | `float` | 距离下次可以下调价格的剩余时间（秒） |

```
{
    "error":"can_lower_every_600_seconds",
    "time_to_lowering":513,
    "code":6
}
```

#### 9. `cancel_order` <a href="#id-9-cancel_order" id="id-9-cancel_order"></a>

**关于**

取消一个活跃订单或现货报价

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段   | 类型    | 必填 | 描述                                                                  |
| ---- | ----- | -- | ------------------------------------------------------------------- |
| `id` | `int` | 是  | 唯一订单/报价 ID                                                          |
| `问题` | `字符串` | 否  | 如果你遇到服务器的任何问题，可以向以下地址报告 [clore.ai](http://clore.ai/) 团队，最多 2048 个字符 |

**输出**

| 字段     | 类型    | 描述  |
| ------ | ----- | --- |
| `code` | `int` | 状态码 |

**示例**

取消订单/报价

**输入：**\
在此示例中，我们报告的是 GPU #1 的问题；如果你没有问题，请不要包含 issue 字段。\
你可以在 text 字段中写任何消息，我们会对其进行调查

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "id":39,
    "issue":"GPU #1 过热并降频"
}' 'https://api.clore.ai/v1/cancel_order'
```

**输出：**

```
{
  "code": 0
}
```

#### 10. `create_order` <a href="#id-10-create_order" id="id-10-create_order"></a>

**关于**

你可以使用此端点创建现货报价或按需订单

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段                     | 类型      | 必填    | 描述                                                                                                                                                                             |
| ---------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `currency`             | `字符串`   | 是     | 货币名称                                                                                                                                                                           |
| `image`                | `字符串`   | 是     | 来自 dockerhub 的有效镜像                                                                                                                                                             |
| `renting_server`       | `int`   | 是     | 你想租用的服务器 ID                                                                                                                                                                    |
| `type`                 | `字符串`   | 是     | `按需` 或 `现货`                                                                                                                                                                    |
| `spotprice`            | `float` | 视情况而定 | 现货市场上的每日报价，创建现货订单时必填                                                                                                                                                           |
| `ports`                | `对象`    | 否     | 端口转发配置，最多 5 条记录                                                                                                                                                                |
| `env`                  | `对象`    | 否     | <p>环境变量，字符串化后总共限制为 12288 个字符。<br>变量名——最多 128 个字符，且不得包含 <code>-</code><br>变量值——最多 1536 个字符<br>仅保留前 30 个有效变量；其余会被静默丢弃</p>                                                        |
| `jupyter_token`        | `字符串`   | 否     | 带有 jupyter notebooks 的镜像的 Jupyter 令牌，最多 32 个字符 \*                                                                                                                              |
| `ssh_key`              | `字符串`   | 否     | 带有 SSH 的镜像的 SSH 密钥，最多 3072 个字符 \*                                                                                                                                              |
| `ssh_password`         | `字符串`   | 否     | 带有 SSH 的镜像的 SSH 密码，最多 32 个字符 \*                                                                                                                                                |
| `command`              | `字符串`   | 否     | 订单创建后将在服务器上运行的命令                                                                                                                                                               |
| `required_price`       | `float` | 否     | 指定你希望订单以何种价格开始；如果机器所有者更改了价格，则订单不会启动（仅按需）                                                                                                                                       |
| `gpu_count`            | `int`   | 否     | 在支持以下功能的服务器上要租用的 GPU 数量 [部分租用](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/mian-xiang-zu-ke/partial-gpu-rental.md)。省略则租用整台机器。仅按需，仅支持同构机器                                    |
| `gpu_indices`          | `[]int` | 否     | 要租用的基于 0 的 GPU 插槽索引；长度必须等于 `gpu_count`。从自由插槽中取用 `partial_gpu_rental.free_indices`。省略则让后端自动选择空闲 GPU                                                                             |
| `autossh_entrypoint`   | `bool`  | 否     | 使用 clore.ai 入口点，它会自动部署 SSH 服务器和自定义 `/root/onstart.sh` 脚本                                                                                                                       |
| `rental_hours`         | `int`   | 否     | 仅按需。你希望机器租用多久，以 1 到 3000 的整小时计（平台上限），从订单创建时开始计算。省略则表示不限制：此时订单在服务器的 `mrl` 除非 `auto_renew` 已开启，在这种情况下会一直运行直到你取消。高于服务器 `mrl` 需要 `auto_renew: true`；等于或低于它的值会在经过相应小时数后结束订单。对现货订单忽略 |
| `auto_renew`           | `bool`  | 否     | 仅按需。当服务器达到最大租赁时长时，只要该价格不高于 `auto_renew_max_price`，就在同一容器上按服务器当前价格续费该订单，直到 `rental_hours` 被使用，或在 `rental_hours` 被省略时直到你取消。续费不收取创建费。对现货订单以及其 `auto_renew_allowed` 为 `false`      |
| `auto_renew_max_price` | `float` | 视情况而定 | 在以下情况时必填 `auto_renew` 为 `true`。订单所使用货币的每日价格上限，必须大于 0 且不超过该市场对该货币的最高价格（0.1 BTC、5,000,000 CLORE、10,000 USD）。在每次续费时，它会与服务器的每日价格比较，并按 `gpu_count` 部分租赁时                            |

\* 对带星号的字段，你只能输入来自此正则分组的字符 `/^[a-zA-Z0-9\s-=.@+/]+$/`

**输出**

| 字段     | 类型    | 描述                                                                                                                                                                                                                                                                                                                                                                             |
| ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code` | `int` | 状态码                                                                                                                                                                                                                                                                                                                                                                            |
| `错误`   | `字符串` | 在代码为以下时出现 `6` （HTTP 200），当订单被拒绝时。租赁时长和自动续费拒绝： `invalid_rental_hours` （不是 1 到 3000 之间的整数，或者 `空值`), `rental_hours_exceeds_mrl` （高于服务器的 `mrl` 没有 `auto_renew: true`), `invalid_auto_renew` (`auto_renew` 不是布尔值，或者它是 `true` 没有正的 `auto_renew_max_price`，或者超过了该货币的市场最高价格）， `auto_renew_not_supported` (`auto_renew: true` 在现货订单上）， `auto_renew_not_allowed` （服务器不允许自动续费）。现货报价拒绝如下所述 |

> **低于服务器下限的现货报价** 会被拒绝，并附带当前最低价，因此你可以立即重试：
>
> ```
> { "error": "too_low_price", "min_price": 0.0000012, "code": 6 }
> ```
>
> 该下限会根据实时币价大约每 10 分钟重新计算一次，因此从市场列表读出的价格可能会略显过时——重试时请始终使用返回的 `min_price` 。
>
> **当服务器已经有同币种的现货报价时**，新的报价必须至少比最高报价高 1%（按该货币精度向上取整，并受价格上限限制）。更低的报价会被拒绝，并返回最低可接受价格：
>
> ```
> { "error": "below_min_raise_step", "min_price": 0.00000425, "code": 6 }
> ```

**示例**

**输入 1（创建现货报价）：**

```
curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency":"bitcoin",
    "image":"cloreai/ubuntu20.04-jupyter",
    "renting_server":6,
    "type":"spot",
    "spotprice":0.000001,
    "ports":{
        "22":"tcp",
        "8888":"http"
    },
    "env":{
        "VARIABLE_NAME":"VARIABLE_VALUE",
    },
    "jupyter_token":"hoZluOjbCOQ5D5yH7R",
    "ssh_password":"Hpcj08ZaOpCbTmn1Eu",
    "command":"#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'
```

**输出 1（创建现货报价）：**

```
{
  "code":0
}
```

**输入 2（创建按需订单）：**

```
curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency":"bitcoin",
    "image":"cloreai/ubuntu20.04-jupyter",
    "renting_server":6,
    "type":"on-demand",
    "ports":{
        "22":"tcp",
        "8888":"http"
    },
    "env":{
        "VARIABLE_NAME":"VARIABLE_VALUE",
    },
    "jupyter_token":"hoZluOjbCOQ5D5yH7R",
    "ssh_password":"Hpcj08ZaOpCbTmn1Eu",
    "command":"#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'
```

**输出 2（创建按需订单）：**

```
{
  "code":0
}
```

**输入 3（48 小时按需订单并自动续期）：**

```
curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency":"CLORE-Blockchain",
    "image":"cloreai/jupyter:ubuntu24.04-v2",
    "renting_server":6,
    "type":"on-demand",
    "rental_hours":48,
    "auto_renew":true,
    "auto_renew_max_price":250
}' 'https://api.clore.ai/v1/create_order'
```

**输出 3（48 小时按需订单并自动续期）：**

```
{
  "code":0
}
```

在一台 24 小时的服务器上 `mrl` 第一个期限持续 24 小时。到期时，订单会按当时服务器价格再续 24 小时；如果价格不超过每天 250 CLORE，则随后由于请求的 48 小时已用尽而结束。使用 `auto_renew` 开启后，省略 `rental_hours` 会持续续期，直到你取消。若不使用 `auto_renew`，同样的 `rental_hours` 在该服务器上的请求会被拒绝：

```
{ "error": "rental_hours_exceeds_mrl", "code": 6 }
```

#### 11. `租客费用` <a href="#id-11-renter_fees" id="id-11-renter_fees"></a>

**关于**

获取当前费用配置：基础租客费用、PoH 费用减免设置、订单创建费用以及你的 PoH 余额

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**输出**

| 字段                        | 类型      | 描述                     |
| ------------------------- | ------- | ---------------------- |
| `code`                    | `int`   | 状态码                    |
| `租客费用.按需`                 | `对象`    | 按需订单每种货币的基础费用（%）       |
| `租客费用.现货`                 | `对象`    | 现货订单每种货币的基础费用（%）       |
| `PoH 配置.最大减免百分比`          | `int`   | 通过 PoH 可获得的最大基础费用减免（%） |
| `PoH 配置.达到最大减免所需的 PoH 余额` | `int`   | 达到最大减免时的 PoH 余额        |
| `创建费用.按需`                 | `对象`    | 每种货币的订单创建费用            |
| `创建费用.现货`                 | `对象`    | 每种货币的现货订单创建费用          |
| `PoH 余额`                  | `float` | 你的 PoH CLORE 余额        |

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/renter_fees'
```

**输出：**

```
{
  "renter_fees": {
    "on_demand": {
      "base": { "bitcoin": 5, "CLORE-Blockchain": 5, "USD-Blockchain": 5 }
    },
    "spot": {
      "base": { "bitcoin": 1.25, "CLORE-Blockchain": 1.25, "USD-Blockchain": 1.25 }
    }
  },
  "poh_config": { "max_reduction_percent": 50, "max_poh_amount": 2000000 },
  "creation_fees": {
    "on_demand": { "bitcoin": 3e-7, "CLORE-Blockchain": 0.5, "USD-Blockchain": 0.1 },
    "spot": { "bitcoin": 1e-7, "CLORE-Blockchain": 0.05, "USD-Blockchain": 0.005 }
  },
  "poh_balance": 5000,
  "code": 0
}
```

#### 12. `取消订单` <a href="#id-12-cancel_orders" id="id-12-cancel_orders"></a>

**关于**

一次取消多个订单（每次请求最多 256 个）

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段      | 类型      | 必填 | 描述                 |
| ------- | ------- | -- | ------------------ |
| `订单 ID` | `[]int` | 是  | 要取消的订单 ID，最多 256 个 |

**输出**

| 字段     | 类型      | 描述         |
| ------ | ------- | ---------- |
| `code` | `int`   | 状态码        |
| `无法取消` | `[]int` | 无法取消的订单 ID |

**输入：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_ids": [38, 39]
}' 'https://api.clore.ai/v1/cancel_orders'
```

**输出：**

```
{
  "failed_to_cancel": [],
  "code": 0
}
```

#### 13. `PoH 余额` <a href="#id-13-poh_balance" id="id-13-poh_balance"></a>

**关于**

获取你的持仓证明余额：项目、总额和 PoH 市场报价金额

**请求头**

| 字段     | 类型    | 必填 | 描述     |
| ------ | ----- | -- | ------ |
| `auth` | `字符串` | 是  | API 令牌 |

**输出**

| 字段               | 类型      | 描述             |
| ---------------- | ------- | -------------- |
| `code`           | `int`   | 状态码            |
| `项目`             | `[]对象`  | 带有单独余额的 PoH 项目 |
| `余额.总计`          | `float` | 所有项目的 PoH 总余额  |
| `余额.未承诺金额`       | `float` | 未用于报价的 PoH 余额  |
| `余额.奖励金额`        | `float` | 符合奖励条件的余额      |
| `余额.报价.已出租金额`    | `float` | 租给其他用户的金额      |
| `余额.报价.已在市场出租金额` | `float` | 在 PoH 市场上挂牌的金额 |
| `余额.报价.已租入金额`    | `float` | 从其他用户租入的金额     |

**输入：**

```
curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/poh_balance'
```

**输出：**

```
{
  "items": [ { "balance": 5000 } ],
  "balance": {
    "total": 5000,
    "free_amount": 4000,
    "reward_amount": 5000,
    "offers": {
      "rented_amount": 0,
      "rented_on_marketplace_amount": 1000,
      "rented_finished_amount": 0,
      "leased_amount": 0
    }
  },
  "code": 0
}
```

#### 14. `server-config.json` <a href="#id-14-server-config-json" id="id-14-server-config-json"></a>

**关于**

获取静态 API 配置数据。无需身份验证

**输入：**

```
curl -XGET 'https://api.clore.ai/v1/server-config.json'
```

#### 15. `获取中继` <a href="#id-15-get_relay" id="id-15-get_relay"></a>

**关于**

获取适用于你检测到的国家/地区的 TCP 转发中继节点。无需身份验证

**输出**

| 字段      | 类型    | 描述          |
| ------- | ----- | ----------- |
| `code`  | `int` | 状态码         |
| `国家/地区` | `字符串` | 检测到的国家/地区代码 |
| `节点`    | `对象`  | 可用中继节点      |

**输入：**

```
curl -XGET 'https://api.clore.ai/v1/get_relay'
```

#### 16. `set_order_auto_renew` <a href="#id-16-set_order_auto_renew" id="id-16-set_order_auto_renew"></a>

**关于**

更改你当前按需订单的请求租期、自动续期及其价格上限。只发送你想更改的字段；省略的字段将保持当前值。仅支持 POST；GET 会返回 code `4`.

* 当前期限随后将在请求的结束时间或 `term_start + term_mrl`，以先到者为准，并且不会早于从现在起 60 秒内结束。 `mrl` 和 `term_end` 进行更改以匹配。超出 `term_start + term_mrl` 需要 `auto_renew`，并且在期限结束时续期会重新定价。
* 将请求延长到 `term_start + term_mrl` 之后，只能在 `auto_renew` 开启时才可行；否则会被拒绝，并返回 `rental_hours_exceeds_mrl`。将已设置的 `rental_hours` 为 `空值` 时 `auto_renew` 保持关闭状态也算作延长，而一项将 `auto_renew` 关闭，同时发送新的 `rental_hours` 其结束时间晚于 `term_start + term_mrl` 的更改也会以同样方式被拒绝。
* 在不切换 `auto_renew` 关闭的情况下缩短请求总是被接受，切换 `auto_renew` 关闭且不设置新小时数，或者设置为 `rental_hours: null`。如果新的 `rental_hours` 已经用尽，则订单会在更改后约一分钟结束。要立即停止租用，请使用 [`cancel_order`](#id-9-cancel_order).
* `rental_hours: null` 会移除请求的限制：在 `auto_renew` 开启时，订单将一直运行，直到你取消。
* 从期限结束前 60 秒起，直到期限已续期或订单已结束为止，该更改都会被拒绝，并返回 `renewal_in_progress`。请使用 [`my_orders`](#id-5-my_orders) 重新读取订单并重试。
* 对于在自动续期功能发布之前创建的订单，第一次更改会将 `term_start` 设置为创建时间，并将 `term_mrl` 设置为订单的 `mrl`，因此如果没有 `auto_renew` ，它就无法超过原始结束时间。

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段                     | 类型            | 必填    | 描述                                                                              |
| ---------------------- | ------------- | ----- | ------------------------------------------------------------------------------- |
| `order_id`             | `int`         | 是     | 唯一订单 ID                                                                         |
| `rental_hours`         | `int` \| `空值` | 否     | 新的请求时长，按整小时计算（1 到 3000），从订单创建时开始计。 `空值` 会移除请求的限制。省略它可保留当前值                      |
| `auto_renew`           | `bool`        | 否     | 当前期限结束时按主机当前价格续期。省略它可保留当前值。当服务器的 `auto_renew_allowed` 为 `false`                 |
| `auto_renew_max_price` | `float`       | 视情况而定 | 以订单货币计价的每日价格上限，大于 0 且不超过市场对该货币的最高价格。当此更改将 `auto_renew` 开启且订单尚无上限时必填；否则省略以保留当前上限 |

**输出**

| 字段     | 类型    | 描述                                                                                                                                                                                                                                                                                                                                                             |
| ------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | `int` | 状态码。 `2` （HTTP 400）当正文类型错误时，例如缺失或非整数的 `order_id`, `rental_hours` 既不是整数也不是 `空值`，非布尔值的 `auto_renew` 或非数值的 `auto_renew_max_price`；这会在下面任何错误之前进行检查                                                                                                                                                                                                                 |
| `错误`   | `字符串` | 在代码为以下时出现 `6` （HTTP 200）： `你不拥有此订单` （订单不存在或不属于你）， `订单未激活` （现货或已关闭的订单、正在取消的订单，或在保存更改时已结束的订单）， `renewal_in_progress` （当前期限将在 60 秒内结束，或在保存更改时订单已发生变化；请重新读取订单并重试）， `invalid_rental_hours` （小于 1 或大于 3000）， `rental_hours_exceeds_mrl` （见上方规则）， `invalid_auto_renew` (`auto_renew` 最终在没有有效价格上限的情况下开启）， `auto_renew_not_allowed` （该更改会将 `auto_renew` 开启，而服务器不允许自动续期） |

**示例**

**输入 1（持续续订直到取消）：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":12345,
    "rental_hours":null,
    "auto_renew":true,
    "auto_renew_max_price":30
}' 'https://api.clore.ai/v1/set_order_auto_renew'
```

**输出 1（持续续订直到取消）：**

```
{
  "code": 0
}
```

**输入 2（停止续订，订单在当前期限结束）：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":12345,
    "auto_renew":false
}' 'https://api.clore.ai/v1/set_order_auto_renew'
```

**输出 2（停止续订，订单在当前期限结束）：**

```
{
  "code": 0
}
```

如果在期限最后 60 秒内发送相同请求，则会被拒绝，直到订单已续期或结束：

```
{ "error": "renewal_in_progress", "code": 6 }
```

#### 17. `order_renewals` <a href="#id-17-order_renewals" id="id-17-order_renewals"></a>

**关于**

获取订单的续期历史：在每个期限结束时作出的每条续期决定一行，包含续期或拒绝，按最新优先，最多 1000 行。从未达到续期决定的订单会返回空列表，而当订单因请求小时数用尽而停止时，其结束点不会留下任何行。仅支持 POST；GET 会返回 code `4`.

**请求头**

| 字段             | 类型    | 必填 | 描述                     |
| -------------- | ----- | -- | ---------------------- |
| `auth`         | `字符串` | 是  | API 令牌                 |
| `Content-Type` | `字符串` | 是  | 必须是 `application/json` |

**请求体**

| 字段         | 类型    | 必填 | 描述      |
| ---------- | ----- | -- | ------- |
| `order_id` | `int` | 是  | 唯一订单 ID |

**输出**

| 字段                         | 类型      | 描述                                                                                                                                                                                   |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`                     | `int`   | 状态码。 `2` （HTTP 400）当 `order_id` 缺失或不是整数                                                                                                                                              |
| `错误`                       | `字符串`   | `你不拥有此订单` 并返回 code `6` （HTTP 200）当订单不存在或不属于你时                                                                                                                                        |
| `续期记录`                     | `[]对象`  | 续期决定，按最新优先；仅在成功时返回                                                                                                                                                                   |
| `renewals[x].order_id`     | `int`   | 唯一订单 ID                                                                                                                                                                              |
| `renewals[x].renewal_no`   | `int`   | 此续期在该订单所有续期中的编号，或本应拥有的编号，从 1 开始计数                                                                                                                                                    |
| `renewals[x].outcome`      | `字符串`   | `已续期` 或 `已拒绝`                                                                                                                                                                        |
| `renewals[x].reason`       | `字符串`   | 仅适用于被拒绝的行： `price_above_cap`, `server_unlisted`, `host_disallowed`, `server_reserved` 或 `insufficient_balance` （参见 `orders[x].auto_renew_declined` 在 [`my_orders`](#id-5-my_orders)) |
| `renewals[x].decided_at`   | `int`   | 作出该决定时的 UNIX 时间，发生在期限结束时                                                                                                                                                             |
| `renewals[x].applied_at`   | `int`   | 确认续期已生效时的 UNIX 时间。拒绝时以及未被确认的续期决定中不存在；当订单在同一时刻被取消或更改时，决定可以保持未应用状态                                                                                                                     |
| `renewals[x].old_price`    | `float` | 已结束期限的每日价格                                                                                                                                                                           |
| `renewals[x].new_price`    | `float` | 新期限的每日价格；若被拒绝，则为被拒绝的主机价格；当无法计算价格时不存在                                                                                                                                                 |
| `renewals[x].cap`          | `float` | 作出决定时你的每日价格上限                                                                                                                                                                        |
| `renewals[x].term_seconds` | `int`   | 新期限的长度（秒）； `0` 在被拒绝时                                                                                                                                                                 |
| `renewals[x].term_start`   | `int`   | 新期限开始时的 UNIX 时间（即上一期限的结束时间）；在被拒绝时，则为已结束期限的开始时间                                                                                                                                       |
| `renewals[x].term_end`     | `int`   | 新期限结束时的 UNIX 时间；在被拒绝时，则为已结束期限的结束时间                                                                                                                                                   |

**示例**

**输入：**

```
curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":12345
}' 'https://api.clore.ai/v1/order_renewals'
```

**输出：**

在这个示例中，订单以每天 24 的价格续期一次，未超过 30 的上限。在该期限结束时，主机价格为 36，高于上限，因此续期被拒绝，订单也在该期限结束。

```
{
  "renewals": [
    {
      "order_id": 12345,
      "renewal_no": 2,
      "outcome": "declined",
      "reason": "price_above_cap",
      "decided_at": 1792209661,
      "old_price": 24,
      "new_price": 36,
      "cap": 30,
      "term_seconds": 0,
      "term_start": 1792188060,
      "term_end": 1792209660
    },
    {
      "order_id": 12345,
      "renewal_no": 1,
      "outcome": "renewed",
      "decided_at": 1792188061,
      "applied_at": 1792188061,
      "old_price": 20,
      "new_price": 24,
      "cap": 30,
      "term_seconds": 21600,
      "term_start": 1792188060,
      "term_end": 1792209660
    }
  ],
  "code": 0
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clore.ai/clore.ai/clore.ai-eng-zh/mian-xiang-zhu-ji-fang/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
