API 文档

为了方便用户灵活调用 GPU 资源，平台提供通过API调用方式使用实例相关功能，目前仅对企业用户开放。

API概览

平台对外提供的API如下:

API	说明
获取平台GPU类型	查询平台当前可用显卡类型
获取镜像	查询当前账户可用的镜像，包括平台官方镜像和自定义镜像
创建实例	创建实例，根据平台推荐规则选择符合条件的最优机器执行创建计划。
查询操作结果	查询实例操作结果
查询实例	查询结果返回未释放实例
实例操作	OpenAPI支持实例开机、关机、重启、释放和设置自定义端口，更多复杂操作请到网页端执行。

如何调用API

1. 申请企业资质

API当前只针对企业用户开放，未开通企业资质请前往账户中心提交企业认证申请。

2. 创建API密钥

API调用需要先创建API 密钥，可以在"账户中心 - OpenAPI 密钥"页面创建密钥，点击添加后即下载密钥到本地，后续无法再重复下载，请妥善保管，切勿泄露。

3. 终端节点

终端节点即调用API的请求地址目前平台提供的服务器调用地址如下：

请求地址	协议类型
`https://api-ai.capitalonline.net`	HTTPS

4. 认证鉴权

所有API接口须要通过在header中携带平台的 API 密钥来进行身份认证。在 Header 中携带 API 密钥的消息头域格式如下:

{
  "gz-api-token":"test123abcxxxxxxxxx"
}

其中 **gm-api-token **是平台自定义header key。

5. 返回结果

API 请求返回统一使用 JSON (对应请求/响应header为Content-Type: application/json) 格式，通用结构如下：

{
  "code": 0,
  "message": "success",
  "traceid": "",
  "data": {}
}

返回结果参数说明：

消息元素名	描述
code	请求响应码，请求成功时为 0，失败时为相应的错误码，具体错误码请参考附录错误码说明。
message	请求成功为 success, 请求失败为具体的业务错误信息
data	返回的业务数据

API详情

1. 获取平台GPU类型

接口说明

请求URI：/api/v1/openapi/gpu/list
请求方法：GET

请求参数 无 返回结果

参数名称	类型	描述
gpus	`Array<string>`	显卡类型数组，显卡类型一致

返回值示例

{
    "code": 0,
    "message": "success",
    "traceid": "",
    "data": {
        "gpus": [
            "G40-24G",
            "G30-24G",
            "A100-PCIE-40G"
        ]
    }
}

2. 获取可用数据中心ID

接口说明

请求URI：/api/v1/openapi/datacenter/list
请求方法：GET

请求参数 无 返回结果

参数名称	类型	描述
datacenters	`Array<Datacenter>`	数据中心数组

Datacenter

参数名称	类型	描述
name	String	数据中心名称
dcId	String	数据中心ID

返回值示例

{
  "code": 0,
  "message": "success",
  "traceid": "57cbd46995d11318814a78746318bc32",
  "data": {
    "datacenters": [
      {
        "name": "宿迁B区",
        "dcId": "suqian-b"
      },
      {
        "name": "庆阳A区",
        "dcId": "qingyang-a"
      },
      {
        "name": "美国-达拉斯N区",
        "dcId": "dallas-n"
      }
    ]
  }
}

2. 获取镜像

接口说明

请求URI：/api/v1/openapi/image/list
请求方法：GET

请求参数 无 返回参数 Image参数描述

参数名称	类型	描述
type	String	镜像类型，user / official, user:备份镜像，official: 官方镜像
imageId	String	镜像Id，创建实例使用
name	String	镜像名称

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "90223a7f6632b1176c74fa17445cfe0e",
    "data": {
        "images": [
            {
                "type": "official",
                "name": "torch2.1.1-cuda12.1.0-py3.10",
                "imageId": "torch2.1.1-cuda12.1.0-py3.10"
            },
            {
                "type": "user",
                "name": "testimage",
                "imageId": "123abc"
            },
        ]
    }
}

3. 创建实例

接口说明

请求URI：/api/v1/openapi/instance/create
请求方法：POST

请求参数 Body

参数名称	类型	必填	描述
type	Integer	是	type类型值，当前仅支持type=2
gpuName	String	是	显卡类型，可通过获取显卡列表接口查询，或者从官网查询
skuName	String	是	支付方式, 取值范围: 按量付费(payg),竞价(bidding),包天(daily),包周(weekly),包月(monthly)
gpuNum	Integer	是	租用显卡数量
cpuNum	Integer	否	单卡分配cpu核心数
memory	Integer	否	单卡分配的内存
diskType	String	否	磁盘类型(SSD/NVME)
tags	`Array<String>`	否	查询符合某些标签的机器
imageId	String	是	创建实例使用的镜像ID，可通过查询可用镜像列表获取
autoRenew	Boolean	否	是否设置到期自动续费，按量付费默认为自动续费，其他预付费支付方式默认为false
duration	Integer	否	预付费实例租用周期，默认为 1
name	String	否	实例名称
servicePort	`Array<Integer>`	否	自定义服务端口,最多设置3个服务端口
cmd	String	否	启动命令
env	String	否	环境变量
dryRun	Boole	否	空跑，为 true 时只做机器筛选和价格检查
dcId	String	否	数据中心ID

返回参数 Data

参数名称	类型	描述
instanceId	Int64	实例ID, dryRun=true时为0
operationId	Int64	当前操作ID， dryRun=true时为 0
spec	`Object<Spec>`	实例规格

Spec

参数名称	类型	描述
gpuName	String	显卡名称
vram	String	单卡显存大小，单位：G
skuName	String	支付类型，取值范围：按量付费(payg),竞价(bidding),包天(daily),包周(weekly),包月(monthly)
price	String	单价
cpuName	String	cpu 型号
cpuCoreNum	int	cpu 核心数，根据租用卡数按比例分配
memorySize	int	内存大小，根据租用卡数按比例分配
payByVoucher	int	是否支持代金券支付, 支持:1, 不支持:0
regionName	String	所在区域
dcId	String	所在数据中心

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "905b8753fb3db11760f67138872918cb",
    "data": {
        "InstanceId": 512300905672709,
        "operationId": 512303116840965,
        "spec": {
            "gpuName": "G30-24G",
            "vram": "10G",
            "skuName": "payg",
            "price": "10",
            "cpuCoreNum": 16,
            "cpuName": "Intel Xeon Processor (Skylake, IBRS)",
            "memorySize": 17179869184,
            "payByVoucher": 1,
            "regionName": "华东",
            "dcId": "suqian-b"
        }
    }
}

4. 查询操作状态

接口说明

请求URI：/api/v1/openapi/instance/op/result
请求方法：POST

请求参数 Body

参数名称	类型	必填	描述
ids	`Array<int>`	是	操作ID列表

返回参数 Operation

参数名称	类型	描述
instanceId	Int64	实例ID
status	int	操作完成状态进行中：1，成功：2，失败：3
action	String	当前进行中的操作
operationId	String	当前操作ID
isCompleted	int	操作是否已完成, 已完成:1, 未完成: 0
startTime	String	开始时间
completeTime	String	完成时间

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "287bfb0b8e3fb11797f57d7a4f92b05b",
    "data": {
        "operations": [
            {
                "instanceId": 512300905672709,
                "operationId": 512303116840965,
                "action": "stop",
                "status": 2,
                "isCompleted": 1,
                "startTime": "2024-02-06 17:06:45",
                "completeTime": "2024-02-06 17:06:47"
            }
        ]
    }
}

5. 查询实例列表

接口说明

请求URI：/api/v1/openapi/instance/query
请求方法：GET

请求参数 Query

参数名称	类型	必填	描述
status	String	否	实例状态, 可选枚举值: stopd, running, creating
instanceId	Int	否	查询单个实例
pn	Integer	否	分页页码
ps	Integer	否	每页大小,默认为20

返回参数

参数名称	类型	描述
instances	`Array<Instance>`	实例数组
total	Integer	总数

Instance

参数名称	类型	描述
instanceId	int64	实例ID
name	String	自定义实例名称
imageId	String	镜像ID
status	String	实例状态
isPending	Int	是否操作执行中, 1 为操作中
gpuName	String	显卡名称
gpuNum	Integer	显卡数量
availableGpuNum	Int	实例所在物理机可用显卡数
skuName	String	租用方式: payg(按量付费), daily(包天), weekly(包周), monthly(包月),card_less(无卡启动)
createdAt	String	创建时间
cpuCoreNum	Int	cpu核心数
memorySize	Int64	内存大小,单位 Byte
systemDiskSize	Int64	系统盘分配空间(根目录/)，单位byte
systemDiskUsedSize	Int64	系统盘已用空间(根目录/), 单位byte
dataDiskSize	Int64	数据盘分配空间(/gz-data)，单位byte
dataDiskUsedSize	Int64	数据盘已用空间(/gz-data), 单位 byte
sshCmd	String	ssh 登录命令
sshPwd	String	ssh 登录密码
notebookUrl	String	JupyterLab Notebook 访问地址
tensorboardUrl	String	Tensorboard 访问地址
customServices	`Array<String>`	自定义端口访问地址（数组，每个元素为一个端口的对应访问地址）
operationId	Int64	实例最近一次操作id
dcId	String	数据中心ID
isStartable	Boolean	是否可以直接启动,根据所在物理机状态及剩余显卡数是否满足实例要求确定

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "3082737a3085b5177f74d5555f57a69f",
    "data": {
        "instances": [
            {
                "instanceId": 504838617333765,
                "name": "testname",
                "status": "stopd",
                "imageId": "stable-diffusion-webui_v1.7.0",
                "isPending": 0,
                "gpuName": "G40-24G",
                "gpuNum": 0,
                "skuName": "payg",
                "operationId": 511642810499077,
                "cpuCoreNum": 1,
                "memorySize": 2147483648,
                "systemDiskSize": 32212254720,
                "systemDiskUsedSize": 4311059,
                "dataDiskSize": 53687091200,
                "dataDiskUsedSize": 0,
                "sshCmd": "ssh -p 59064 root@xxxxx",
                "sshPwd": "Q3rDHh7QEwgYsuPxYSdVbE9zzKQQW45e",
                "notebookUrl": "http://xxxxx:42757/lab?token=f4jzygqwno3fecinx9arnetu",
                "tensorboardUrl": "http://xxxxx:44634",
                "customServices": [
                    "http://xxxxx:48548"
                ],
                "createdAt": "2024-01-16 14:53:38",
                "dcId": "qingyang-a",
                "availableGpuNum": 8,
                "isStartable": true
            }
        ],
        "total": 1
    }
}

6. 实例操作

接口说明

请求URI：/api/v1/openapi/instance/action
请求方法：POST

请求参数 Body

参数名称	类型	必填	描述
instanceId	Int64	是	实例ID
action	String	是	实例操作名称，仅支持stop(实例关机), start(开机), restart(重启), release(释放), set_port(设置自定义端口)
ports	`Array<Int>`	否(action=set_port时必填)	内部端口号数组,最多同时开启3个,需要先完成实名认证或企业认证

返回参数

参数名称	类型	描述
operationId	Int64	操作ID

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "3082737a3085b5177f74d5555f57a69f",
    "data": {
      "operationId": 511642810499077
    }
}

附录

1. 请求返回的通用结构

{
  "code": 0,
  "message": "success",
  "traceid": "180114fedf26b1177b44121fa5c1e5d9",
  "data": {}
}

2. HTTP状态码

状态码	含义	描述
404	Not Found	请求URI不存在
403	Forbidden	请求未授权
200	OK	请求成功
500	Internal Server Error	服务器错误

3. 常用错误码

错误码	错误信息	描述
10001	服务器内部错误	未定义的服务器内部错误, 可提供单反馈协助解决
10002	未登录或者登录已过期	一般是请求header 中缺少gz-api-token
10005	参数错误	参数校验错误
10135	实例操作错误	实例操作错误，错误信息在 message 中

API概览​

如何调用API​

1. 申请企业资质​

2. 创建API密钥​

3. 终端节点​

4. 认证鉴权​

5. 返回结果​

API详情​

1. 获取平台GPU类型​

2. 获取可用数据中心ID​

2. 获取镜像​

3. 创建实例​

4. 查询操作状态​

5. 查询实例列表​

6. 实例操作​

附录​

1. 请求返回的通用结构​

2. HTTP状态码​

3. 常用错误码​

API概览

如何调用API

1. 申请企业资质

2. 创建API密钥

3. 终端节点

4. 认证鉴权

5. 返回结果

API详情

1. 获取平台GPU类型

2. 获取可用数据中心ID

2. 获取镜像

3. 创建实例

4. 查询操作状态

5. 查询实例列表

6. 实例操作

附录

1. 请求返回的通用结构

2. HTTP状态码

3. 常用错误码