仅对企业用户开放的OpenAPI文档【GpuMall智算云】

GpuMall智算云
151 阅读9分钟

​

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

企业体验：GpuMall智算云 | 省钱、好用、弹性。租GPU就上GpuMall

API概览​

平台对外提供的API如下:

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

如何调用API​

1. 申请企业资质​

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

2. 创建API密钥​

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

​编辑

3. 终端节点​

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

请求地址协议类型
https://api.gpumall.comHTTPS

4. 认证鉴权​

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

{
  "gm-api-token":"dWEwmaZxxxxxxxxx"
}

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

5. 返回结果​

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

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

返回结果参数说明：

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

API详情​

1. 获取平台GPU类型​

接口说明

  • 请求URI： /api/v1/open-api/gpu/list
  • 请求方法：GET

请求参数 无 返回结果

参数名称类型描述
gpusArray<string>显卡类型数组 ，与高可用云/社区云的显卡类型一致

返回值示例

{
    "code": 0,
    "message": "success",
    "traceid": "180114fedf26b1177b44121fa5c1e5d9",
    "data": {
        "gpus": [
            "RTX 3090",
            "RTX 4090",
            "RTX 2080 Ti",
        ]
    }
}

2. 获取镜像​

接口说明

  • 请求URI： /api/v1/open-api/image/list
  • 请求方法：GET

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

参数名称类型描述
typeString镜像类型，user / official, user:备份镜像，official: 官方镜像
imageIdString镜像Id，创建实例使用
nameString镜像名称

返回示例

{
    "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": "AnythingV5-WebUI",
                "imageId": "imgbgl8mu4msk375gdsd32smbogsuffm"
            },
        ]
    }
}

3. 创建实例​

接口说明

  • 请求URI： /api/v1/open-api/instance/create
  • 请求方法：POST

请求参数 Body

参数名称类型必填描述
typeInteger是社区云: 1, 高可用云：2
gpuNameString是显卡类型，可通过获取显卡列表接口查询，或者从官网查询
skuNameString是支付方式, 取值范围: 按量付费(payg),竞价(bidding),包天(daily),包周(weekly),包月(monthly)
gpuNumInteger是租用显卡数量
cpuNumInteger否单卡分配cpu核心数
memoryInteger否单卡分配的内存
diskTypeString否磁盘类型(SSD/NVME)
tagsArray<String>否查询符合某些标签的机器
imageIdString是创建实例使用的镜像ID，可通过查询可用镜像列表获取
autoRenewBoolean否是否设置到期自动续费，按量付费默认为自动续费，其他预付费支付方式默认为false
durationInteger否预付费实例租用周期，默认为 1
cmdString否启动命令
envString否环境变量
dryRunBoole否空跑，为 true 时只做机器筛选和价格检查

返回参数 Data

参数名称类型描述
instanceIdInt64实例ID, dryRun=true时为0
operationIdInt64当前操作ID， dryRun=true时为 0
specObject<Spec>实例规格

Spec

参数名称类型描述
gpuNameString显卡名称
vramString单卡显存大小，单位：G
skuNameString支付类型，取值范围：按量付费(payg),竞价(bidding),包天(daily),包周(weekly),包月(monthly)
priceString单价
cpuNameStringcpu 型号
cpuCoreNumintcpu 核心数，根据租用卡数按比例分配
memorySizeint内存大小，根据租用卡数按比例分配
payByVoucherint是否支持代金券支付, 支持:1, 不支持:0
regionNameString所在区域

返回示例

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

4. 查询操作状态​

接口说明

  • 请求URI： /api/v1/open-api/instance/op/result
  • 请求方法：POST

请求参数 Body

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

返回参数 Operation

参数名称类型描述
instanceIdInt64实例ID
statusint操作完成状态 进行中：1，成功：2，失败：3
actionString当前进行中的操作
operationIdString当前操作ID
isCompletedint操作是否已完成, 已完成:1, 未完成: 0
startTimeString开始时间
completeTimeString完成时间

返回示例

{
    "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/open-api/instance/query
  • 请求方法：GET

请求参数 Query

参数名称类型必填描述
statusString否实例状态, 可选枚举值: stopd, running, creating
instanceIdInt否查询单个实例
pnInteger否分页页码
psInteger否每页大小,默认为20

返回参数

参数名称类型描述
instancesArray<Instance>实例数组
totalInteger总数

Instance

参数名称类型描述
instanceIdint64实例ID
nameString自定义实例名称
imageIdString镜像ID
statusString实例状态
isPendingint是否操作执行中, 1 为操作中
gpuNameString显卡名称
gpuNumInteger显卡数量
skuNameString租用方式: payg(按量付费), daily(包天), weekly(包周), monthly(包月),card_less(无卡启动)
createdAtString创建时间
cpuCoreNumIntcpu核心数
memorySizeint64内存大小,单位 Byte
systemDiskSizeint64系统盘分配空间(根目录/)，单位byte
systemDiskUsedSizeint64系统盘已用空间(根目录/), 单位byte
dataDiskSizeint64数据盘分配空间(/gm-data)，单位byte
dataDiskUsedSizeint64数据盘已用空间(/gm-data), 单位 byte
sshCmdStringssh 登录命令
sshPwdStringssh 登录密码
notebookUrlStringJupyterLab Notebook 访问地址
tensorboardUrlStringTensorboard 访问地址
customServicesArray<String>自定义端口访问地址（数组，每个元素为一个端口的对应访问地址）
operationIdint64实例最近一次操作id

返回示例

{
    "code": 0,
    "message": "success",
    "traceid": "3082737a3085b5177f74d5555f57a69f",
    "data": {
        "instances": [
            {
                "instanceId": 504838617333765,
                "name": "AnythingV5-WebUI",
                "status": "stopd",
                "imageId": "stable-diffusion-webui_v1.7.0",
                "isPending": 0,
                "gpuName": "RTX 3080",
                "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"
            }
        ],
        "total": 1
    }
}

6. 实例操作​

接口说明

  • 请求URI： /api/v1/open-api/instance/action
  • 请求方法：POST

请求参数 Body

参数名称类型必填描述
instanceIdInt64是实例ID
actionString是实例操作名称，仅支持stop(实例关机), start(开机), restart(重启), release(释放)

返回参数

参数名称类型描述
operationIdInt64操作ID

返回示例

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

附录​

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

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

2. HTTP状态码​

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

3. 常用错误码​

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

​

avatar
文章
阅读
粉丝