OpenAPI 开发者文档

通过千里云 OpenAPI 查询和管理 GPU 实例、镜像及账户余额。本文介绍接口调用方式、请求参数与响应格式。

接口导航

• 实例 API：实例列表、实例详情、报价、部署、销毁、关机、开机、重启、修改名称、保存镜像

• 镜像 API：镜像列表、镜像详情、销毁镜像

• 账户 API：账户余额

快速开始

接口地址与认证

生产环境 API 基础地址： https://api.qianlicloud.com。以下请求示例均使用该地址。通过千里云控制台获取 API Key，并使用 Bearer 认证。

export QLY_API_BASE="https://api.qianlicloud.com"
export QLY_API_KEY="REPLACE_WITH_API_KEY"

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/instances?page=1&pageSize=20"

GET 接口使用路径或 Query 参数；POST 接口使用 JSON Body，并设置 Content-Type: application/json。

生产环境请始终通过 HTTPS 调用接口。API Key、SSH 密码、Jupyter Token 等敏感信息应妥善保管，不要提交到代码仓库、写入日志或分享给未授权人员。读取实例连接信息时，请确认调用方具备相应权限，并避免将响应内容保存在公开位置。

请求受理与执行完成

• HTTP 200：查询已成功，或接口同步处理成功，具体以响应内容为准。

• HTTP 202：请求已受理，不表示资源操作已经完成。

• 部署实例返回 instanceId，通过实例详情查询创建结果。

• 保存镜像返回 imageId，通过镜像详情查询保存结果。

• 开机、关机、改名等操作，可通过实例详情查询当前资源状态或名称。重启前后实例可能一直显示 RUNNING，因此不能仅凭该状态认定某次重启已完成；需要准确确认单次操作时，请通过技术支持渠道提供请求追踪信息核查。

防止重复提交

部署实例、保存镜像请求必须携带 Idempotency-Key，其他资源操作可以携带。示例：

Idempotency-Key: deploy-instance-example-001

每次新的操作使用不同的键；同一次操作重试时使用相同的键与请求参数。键支持 1～128 个字母、数字或 ._:-。不提供该请求头的可选接口，不能保证网络重试被识别为原操作。

部署实例或保存镜像遇到 REQUEST_RESULT_PENDING 时，请使用原键和原请求体重试，避免重复创建资源。

参数与枚举说明

请求参数表列出各接口可传入的字段；路径参数和请求头参数会在对应字段的说明中标明。响应参数表列出响应顶层字段，复杂对象的具体字段定义见共享数据模型。“必返”表示父对象存在时该字段必定出现；“可为 null”表示字段值可能为空。请求与响应示例用于展示数据结构，具体字段和约束以本文参数表及共享模型为准。

实例列表的 status 查询参数仅支持 RUNNING（运行中）、STOPPED（已关机）、LOCKED（已锁定）、EXPIRED（已到期）。实例响应还可能包含创建、启动、停止等生命周期状态，详见实例状态说明。GPU 型号、计费组件代码和计量单位等配置型取值，以平台实际开放的产品配置及接口响应为准。

公共响应与错误

多数查询返回 requestId 和 data；部署实例、保存镜像及实例操作按各自接口的简洁响应格式返回。发生错误时，通常使用以下结构：

{
  "requestId": "req-example",
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "请求参数不正确。",
    "retryable": false
  }
}

错误响应参数

API Key、SSH 密码与访问令牌属于敏感信息，不应保存在公开代码库、共享测试用例或日志中。

实例 API

返回文档首页 · 镜像 API · 账户 API

实例列表 · 实例详情 · 实例报价 · 部署实例 · 销毁实例 · 关机 · 开机 · 重启 · 修改实例名称 · 保存镜像

实例列表

GET /open/instances

分页查询当前账户可见的实例。status 仅支持4种常用资源状态；已销毁、已回收的资源不参与列表结果及总数统计。

请求参数

响应参数

请求示例

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/instances?page=1&pageSize=20"

响应示例 · HTTP 200

以下为示例响应；GPU_MODEL_EXAMPLE 为示意值，容量及价格仅用于展示响应格式，不代表实际可售规格或计费价格。

{
  "requestId": "req-example",
  "data": {
    "items": [
      {
        "id": "container-example",
        "name": "GPU实例",
        "gpuCount": 1,
        "gpuModel": "GPU_MODEL_EXAMPLE",
        "imageId": "img-example",
        "imageVersionId": null,
        "billingMode": "POSTPAID",
        "status": "RUNNING",
        "createdAt": "2026-10-21T10:00:00Z",
        "expiresAt": null,
        "cpuModel": null,
        "cpuCores": 4,
        "memorySize": "16",
        "systemDiskSize": "50",
        "dataDiskSize": null,
        "dataDiskMountPath": null,
        "storageMountPath": null,
        "price": null,
        "sshPassword": null,
        "jupyterUrl": null,
        "jupyterToken": null,
        "sshCommand": null,
        "systemDiskUsedSize": null,
        "dataDiskUsedSize": null,
        "customServices": []
      }
    ],
    "total": "1",
    "page": 1,
    "pageSize": 20
  }
}

items 与实例详情使用相同的字段结构；列表中的 SSH 密码、Jupyter Token 等敏感连接字段返回 null，不会批量提供连接凭据。total 是符合条件的总记录数，以字符串返回；空列表时 items 为 []。

实例详情

GET /open/instances/{instanceId}

获取实例资源配置、运行状态、挂载路径、预估费用及连接信息。与实例列表共用 Instance 模型。创建请求被受理、但资源仍未交付时，可返回 CREATING；已销毁或已回收的资源不再可查询。

请求参数

响应参数

请求示例

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/instances/REPLACE_INSTANCE_ID"

响应示例 · HTTP 200

{
  "requestId": "req-example",
  "data": {
    "id": "container-example",
    "name": "GPU实例",
    "gpuCount": 1,
    "gpuModel": "GPU_MODEL_EXAMPLE",
    "imageId": "img-example",
    "imageVersionId": null,
    "billingMode": "POSTPAID",
    "status": "RUNNING",
    "createdAt": "2026-10-21T10:00:00Z",
    "expiresAt": null,
    "cpuModel": null,
    "cpuCores": 4,
    "memorySize": "16",
    "systemDiskSize": "50",
    "dataDiskSize": null,
    "dataDiskMountPath": null,
    "storageMountPath": null,
    "price": null,
    "sshPassword": null,
    "jupyterUrl": null,
    "jupyterToken": null,
    "sshCommand": null,
    "systemDiskUsedSize": null,
    "dataDiskUsedSize": null,
    "customServices": []
  }
}

已有预付费实例可包含数据盘和挂载路径，详情按该实例实际配置返回。无法取得的字段返回 null，不以当前商品默认配置代替历史实例的真实规格。

完整实例状态及筛选值的区别见 实例状态说明。

RUNNING 不代表本次重启一定完成。实例详情仅展示当前资源信息，不提供单次异步请求的完成凭据。费用为当前预估值，可能随实例状态或计费规则变化。

实例报价

POST /open/quotes

查询部署后付费实例的预估费用。报价不创建资源、不扣费，也不预留库存。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/quotes" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"gpuModel":"REPLACE_WITH_AVAILABLE_GPU_MODEL","gpuCount":1,"imageId":"REPLACE_IMAGE_ID","systemDiskSize":200}'

响应示例 · HTTP 200

以下金额仅用于说明响应格式，不代表实际价格。

{
  "requestId": "req-example",
  "data": {
    "billingMode": "POSTPAID",
    "estimatedTotal": {"amount": "12.34", "currency": "CNY"},
    "estimatePeriod": {"unit": "MINUTE", "quantity": "60"},
    "components": [
      {
        "code": "CONTAINER_INSTANCE",
        "quantity": "1",
        "unit": "INSTANCE",
        "amount": {"amount": "12.34", "currency": "CNY"},
        "billingPeriod": "MINUTE"
      }
    ],
    "calculatedAt": "2026-10-21T10:00:00Z",
    "binding": false,
    "catalogVersion": "example"
  }
}

estimatedTotal 为预估总额，estimatePeriod 为对应周期，components 为费用明细。金额对象包含 amount（十进制字符串）和 currency（币种）。当无法提供对应估算金额时，estimatedTotal 与 estimatePeriod 可能同时为 null。

部署实例

POST /open/instances

镜像无需指定版本：平台在首次处理创建意图时选定镜像当前可用版本，并持久保留供同一请求重试使用；后续镜像更新不会改变已确定的创建意图。

部署后付费 GPU 实例，返回新实例 ID。该操作可能产生资源费用。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-instance-example-001" \
  --data '{"gpuModel":"REPLACE_WITH_AVAILABLE_GPU_MODEL","gpuCount":1,"imageId":"REPLACE_IMAGE_ID","name":"GPU实例","systemDiskSize":200,"cloudStoragePath":"/root/cloud-storage"}'

响应示例 · HTTP 202

{"instanceId": "container-example"}

202 仅表示请求已受理，使用实例详情查询后续结果。若返回错误码 REQUEST_RESULT_PENDING，使用原幂等键、原请求体重试获取结果，不要发起新的创建意图。

销毁实例

POST /open/instances/destroy

销毁符合条件的已关机后付费实例。销毁可能导致数据无法恢复，请提前备份。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances/destroy" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: destroy-instance-example-001" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID"}'

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

销毁操作成功受理后，实例最终会从可见资源中移除。已销毁资源不再由列表或详情返回；但单独收到 404 并不能证明本次销毁操作成功。

关机

POST /open/instances/stop

关闭运行中的实例。后付费实例关机后释放 GPU，实例和磁盘仍保留，其他费用不一定停止。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances/stop" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID"}'

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

通过实例详情查询当前 status，确认实例已停止（STOPPED）。

开机

POST /open/instances/start

启动符合开机条件的已关机实例。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances/start" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID"}'

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

通过实例详情查询当前 status，确认实例已运行（RUNNING）。

重启

POST /open/instances/restart

重启运行中的实例。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances/restart" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID"}'

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

202 仅表示重启请求已受理。可通过实例详情观察实例运行状态，但重启前后都可能是 RUNNING；仅凭此状态无法确认本次重启已经完成。

修改实例名称

POST /open/instances/rename

修改实例名称。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/instances/rename" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID","name":"新的实例名称"}'

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

查询实例详情，核实实例名称是否已更新。

保存镜像

POST /open/images/save

将实例保存为私有镜像，返回新镜像 ID。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/images/save" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: save-image-example-001" \
  --data '{"instanceId":"REPLACE_INSTANCE_ID","destroyAfterSave":false}'

响应示例 · HTTP 202

{"imageId": "img-example"}

使用镜像详情查询保存进度：PROCESSING 为处理中、AVAILABLE 为可用、FAILED 为失败、UNKNOWN 为结果未确认。保存运行中的实例可能导致关机，且不会自动恢复运行。设为 destroyAfterSave=true 前，请确认销毁来源实例的影响。

镜像 API

返回文档首页 · 实例 API · 账户 API

镜像列表 · 镜像详情 · 销毁镜像

镜像列表

GET /open/images

分页查询当前账户的个人镜像（Self），包含已公开和未公开的本人镜像，不返回系统镜像或其他人的社区镜像。

请求参数

响应参数

请求示例

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/images?page=1&pageSize=20"

响应示例 · HTTP 200

{
  "requestId": "req-example",
  "data": {
    "items": [
      {
        "id": "img-example",
        "name": "本人镜像",
        "imageType": "Self",
        "isPublish": false,
        "versionId": "1.0",
        "sizeBytes": null,
        "status": "AVAILABLE",
        "ownedByCurrentUser": true,
        "createdAt": null,
        "description": null,
        "price": null
      }
    ],
    "total": "1",
    "page": 1,
    "pageSize": 20
  }
}

列表仅返回本人个人镜像，无需指定查询范围。isPublish表示该本人镜像是否已公开；total为记录总数，以字符串返回。

镜像详情

GET /open/images/{imageId}

查询本人个人镜像的属性及当前状态；系统镜像、其他用户镜像及不存在的镜像统一返回404。保存镜像后也使用此接口确认结果。

请求参数

响应参数

请求示例

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/images/REPLACE_IMAGE_ID"

响应示例 · HTTP 200

{
  "requestId": "req-example",
  "data": {
    "id": "img-example",
    "name": "我的镜像",
    "imageType": "Self",
        "isPublish": false,
    "versionId": "1.0",
    "sizeBytes": null,
    "status": "AVAILABLE",
    "ownedByCurrentUser": true,
    "createdAt": null,
    "description": null,
    "price": null
  }
}

镜像不存在或当前账户无权访问时，接口返回 404。

销毁镜像

POST /open/images/destroy

销毁当前账户有权删除的私有镜像。删除后无法继续使用该镜像，请确认没有重要资源依赖。

请求参数

响应参数

请求示例

curl --silent --show-error -X POST \
  "${QLY_API_BASE}/open/images/destroy" \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: destroy-image-example-001" \
  --data '{"imageId":"REPLACE_IMAGE_ID"}'

响应示例 · HTTP 200

{"code": 0, "msg": "删除成功", "success": true}

响应示例 · HTTP 202

{"code": 0, "msg": "请求已受理", "success": true}

HTTP 200 表示镜像删除已完成；HTTP 202 只表示请求已受理，不能认定删除已经完成。镜像不存在、无权删除或状态不允许删除时，按对应 HTTP 错误码处理。

账户 API

返回文档首页 · 实例 API · 镜像 API

账户余额

GET /open/account/balance

查询当前账户的现金余额和赠金余额，单位为人民币元。

请求参数

响应参数

请求示例

curl --silent --show-error \
  -H "Authorization: Bearer ${QLY_API_KEY}" \
  "${QLY_API_BASE}/open/account/balance"

响应示例 · HTTP 200

以下金额仅供格式演示。

{
  "requestId": "req-example",
  "data": {
    "cashBalance": "100.00",
    "giftBalance": "50.00"
  }
}

赠金可能存在适用范围限制，不应将两种余额简单理解为完全可互换的支付金额。

数据模型

以下为接口中复用的数据模型。“必返”表示父对象存在时该字段必定出现；“可为空”表示字段值可能为 null。

响应与共享模型

PageInstance

Page<Instance> 分页模型。用于描述实例列表 data 中的分页结果；每个实例对象的字段见 Instance。

PageImage

Page<Image> 分页模型。用于描述镜像列表 data 中的分页结果；每个镜像对象的字段见 Image。

Instance

实例列表 items 中的每个对象和实例详情的 data 共用此模型。列表中的连接信息字段保持 null，详情根据当前账户的访问权限返回相应数据。状态筛选值请参阅 实例状态说明。

实例状态说明

列表请求的 status 筛选参数仅支持以下4项：

实例详情还可以在资源尚未交付、但创建意图已经持久关联时返回 CREATING（创建中）。实例响应可能出现 PROVISIONING（部署中）、STARTING（开机中）、STOPPING（关机中）、RESTARTING（重启中）、DELETING（销毁中）、SAVING_IMAGE（保存镜像中）、CREATE_FAILED（创建失败）、BACKED_UP（已备份）、STOP_TIMEOUT（关机超时）等现有生命周期值；其他明确中间状态包括 MODIFYING_PASSWORD（修改密码中）、EXPANDING_DISK（磁盘扩容中）、EXPIRING（过期处理中）、RENEWING（续费中）、LOCKING（锁定中）、RECYCLING（回收中）、STARTING_VNC（VNC启动中）、STOPPING_VNC（VNC停止中）、BACKING_UP（备份中）、MIGRATING（迁移中）和 PENDING（等待处理中）。权威状态缺失或无法识别时保留 UNKNOWN。这些不是列表 status 参数允许的筛选值。 UNKNOWN 表示无法确认资源状态，不是某次异步操作的执行结果。

已销毁或已回收的实例不参与列表和 total 统计，也不再通过实例详情返回。列表和详情不提供删除时间字段。

Quote

PricePeriod

Money

PriceComponent

Image

Balance

Error