实例管理API文档

OnethingAI

发布于：2025-06-18

获取开发者密钥

此密钥为平台API操作唯一标识，务必保证不要泄露

❗️登录OneThingAI平台，进入账户中心，选择开发者密钥自助创建密钥

简介

OneThingAI平台向用户开放平台大部分使用相关API。您可以使用本文档介绍的API对您的实例进行管理。

域名：https://api-lab.onethingai.com

内容格式：application/json

必须请求头信息

头名称	内容
Authorization	Bearer {TOKEN}

创建实例的整体流程：

销毁实例的整体流程：

也可以使用以下python 的sdk来操作实例管理 API

sdk 地址： onethingai-pilot ，简单例子： example

参考SDK 例子的代码：

接口列表

通用返回字段说明

字段名	含义	类型	说明
code	返回code	int	0为成功，非0为失败
msg	信息返回	int	返回信息
data	返回内容	data	返回内容

注：实例创建、关机、开机、卸载接口均为单实例操作，不支持批量操作

1、我的镜像列表接口

接口地址：/api/v2/app/private/image/list

接口描述：拉取我的镜像列表接口

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
regionId	区域Id	int	否	区域Id
appImageName	镜像名称	string	否	镜像名称

主要返回字段说明

字段名	含义	类型	说明
appImageId	我的镜像id	string	在创建v2接口使用
appImageDescription	镜像描述	string	镜像描述
appImageName	镜像名称	string	镜像名称
appImageStatus	镜像状态	int	镜像状态 1: 保存中 4: 保存成功 5: 保存失败
appImageTotalSize	镜像大小	float64	单位MB
regionId	区域Id	int	区域Id（对应的镜像ID仅限在对应区域创建）
createdAt	创建时间	int	创建时间戳
updatedAt	更新时间	int	更新时间戳

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v2/app/private/image/list' \
-H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "privateImageList": [
            {
                "appImageDescription": "",
                "appImageId": "PRIVATE_bg2ypp16lc4598yb-m6vubese-ki882u9l",
                "appImageName": "放大",
                "appImageStatus": 4,
                "appImageTotalSize": 79.707,
                "createdAt": 1724585700,
                "regionId": 2,
                "updatedAt": 1724728171
            },
            {
                "appImageDescription": "",
                "appImageId": "PRIVATE_aozzjm3p1st3xm2w-7mkhact9-9wyz0dsw",
                "appImageName": "波普头像",
                "appImageStatus": 4,
                "appImageTotalSize": 12106.064,
                "createdAt": 1723535516,
                "regionId": 2,
                "updatedAt": 1723536042
            }
        ]
    },
    "msg": "Success"
}

2、官方镜像、社区镜像列表接口

接口地址：/api/v1/app/publish/image/list

接口描述：拉取官方镜像、社区镜像列表接口

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
appImageName	镜像名称	string	否	镜像名称
appImageAuthor	镜像作者	string	否	镜像作者

主要返回字段说明

字段名	含义	类型	说明
appImageId	镜像id	string	在创建v2接口使用
appImageName	镜像名称	string	镜像名称
appImageVersion	镜像版本	string	镜像版本
appImageAuthor	镜像作者	string	镜像作者
appImageDescription	镜像描述	string	镜像描述
createdAt	创建时间	int	创建时间戳
updatedAt	更新时间	int	更新时间戳

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/app/publish/image/list?appImageName=PyTorch&appImageAuthor=官方版' \
-H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "publishImageList": [
            {
                "appImageAuthor": "官方版",
                "appImageDescription": "强大的节点式stable diffusion",
                "appImageId": "PUBLIC_6",
                "appImageName": "ComfyUI",
                "appImageVersion": "v0.0.66",
                "createdAt": 1703721600,
                "updatedAt": 1734624600
            },
            {
                "appImageAuthor": "官方版",
                "appImageDescription": "强大的节点式stable diffusion",
                "appImageId": "PUBLIC_63",
                "appImageName": "ComfyUI稳定版",
                "appImageVersion": "v0.0.51",
                "createdAt": 1724331924,
                "updatedAt": 1734624601
            }
        ]
    },
    "msg": "Success"
}

3、资源拉取接口

请求地址：/api/v2/resources

接口描述：获取资源情况，返回参数中的maxGpuNum大于0的GPU类型才可以成功创建实例

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
appImageId	实例镜像id	string	是	实例镜像id，我的镜像列表接口、官方镜像、社区镜像列表接口获取
gpuType	GPU类型	string	否	GPU类型，不填默认查所有
regionId	区域Id	int	否	区域Id，不填默认查所有

主要返回字段说明

字段名	含义	类型	说明
gpuType	GPU类型	string	GPU类型，用于创建实例
regionId	区域Id	int	区域id
maxGpuNum	GPU卡数	int	一个实例容器，可配置GPU卡数（非资源池总卡数）

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v2/resources?appImageId=PUBLIC_6&regionId=6' \
-H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "resourceList": [
            {
                "gpuType": "NVIDIA-A100-PCIE-40GB",
                "regionId": 6,
                "maxGpuNum": 0
            },
            {
                "gpuType": "NVIDIA-GEFORCE-RTX-4090",
                "regionId": 6,
                "maxGpuNum": 2
            },
            {
                "gpuType": "NVIDIA-GEFORCE-RTX-3090",
                "regionId": 6,
                "maxGpuNum": 0
            },
            {
                "gpuType": "NVIDIA-GEFORCE-RTX-3060",
                "regionId": 6,
                "maxGpuNum": 0
            }
        ]
    },
    "msg": "Success"
}

4、实例创建接口

接口地址：/api/v2/app

接口描述：支持官方镜像、社区镜像、我的镜像创建实例

请求方式：POST

请求参数

字段名	含义	类型	是否必填	说明
appImageId	实例镜像id	string	是	实例镜像id，我的镜像列表接口、官方镜像、社区镜像列表接口获取
billType	计费方式	int	是	计费方式，1：包月，2：包天，3：按量
gpuNum	GPU卡数	int	是	实例容器，配置GPU卡数（单个实例内分配的卡数）
regionId	区域Id	int	是	创建实例区域id（若创建我的镜像实例，区域id应该填我的镜像所属区域id）
gpuType	GPU类型	string	是	GPU类型
duration	包卡时间	int	否	用于计费方式为包月、包天的持续时间，如:(包一个月：billType=1,duration=1)，(包一天：billType=2,duration=1)
groupId	分组id	string	否	分组id，32位长度字符串
customPort	自定义端口	[]customPort	否	公网访问自定义端口，最多填入5个端口，若数组数量大于5，只生效前5个
envs	环境变量	[]envs	否	环境变量

envs:

字段名	含义	类型	说明
name	环境变量名称	string	环境变量名称
value	环境变量值	string	环境变量值

customPort:

字段名	含义	类型	说明
localPort	端口	int	自定义端口，范围 0 - 65535
type	端口类型	string	端口类型，http 或者 tcp

curl 请求例子

curl -X POST 'https://api-lab.onethingai.com/api/v2/app' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-d' {
  "appImageId": "PRIVATE_eut5hud01926m5v5-qurjaoaq-vhbamj7l",
  "billType": 3,
  "gpuNum": 1,
  "regionId": 2,
  "gpuType": "NVIDIA-GEFORCE-RTX-4090", 
  "duration":0, 
  "groupId": "",
  "envs":[
        {
            "name": "myenv",
            "value": "import"
        },
        {
            "name": "myenv1",
            "value": "import1"
        }
    ],
  "customPort": [
      {
        "localPort": 1123,
        "type": "http"
      },
      {
        "localPort": 1124,
        "type": "http"
      }]
}'

返回例子

{
    "code":0
    "msg": "Success"
    "data": {
       "appId": "qyejicqiez7iwi7a-byswmjqd",
       "groupId": "xxxxx"  	
   }
}

5、实例列表接口

接口地址：/api/v2/app

接口描述：获取已创建实例列表

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
page	当前页	int	是	当前页
pageSize	每页大小	int	是	每页大小，0 < pageSize <= 100
appId	实例id	string	否	实例id
groupId	分组id	string	否	分组id，32位长度字符串
status	实例状态	int	否	实例状态码
gpuType	gpu类型	string	否	gpu类型
appImageId	镜像id	string	否	镜像id

主要返回字段说明

字段名	含义	类型	说明
appImageId	镜像id	string	镜像id
appImageName	镜像名称	string	镜像名称，如：Stable Diffusion 1.8
appImageAuthor	镜像作者	string	镜像作者，如：官方版
appImageVersion	镜像版本	string	镜像版本，如：v1.8
billType	计费方式	int	计费方式，1：包月，2：包天，3：按量
errCode	实例错误码	int	实例错误码，非0为异常错误码
systemDiskSize	磁盘大小	float64	磁盘总大小，单位：MB
systemDiskSizeUsed	磁盘使用大小	float64	磁盘使用大小，单位：MB
gpuType	GPU类型	string	gpu类型
appId	实例id	string	实例id
prePrice	预扣金额	float64	预扣金额
price	单价/min	float64	每分钟单价
regionId	区域Id	int	区域Id
status	实例状态	int	实例状态：部署中：100，开机中：200，运行中：300，关机中： 400，重置中： 500，更换镜像中：600，释放资源中：700，已关机：800
webUIAddress	webUI地址	string	webUI地址
createdAt	创建时间	int	实例创建时间戳
runningAt	实例开始运行时间	int	实例运行时间戳（按量计费实例生效）
stoppedAt	关机时间	int	实例关机时间戳
expiredAt	释放时间	int	实例释放时间戳
startedAt	最后一次开机时间	int	最后一次开机时间戳
runtime	当前运行时长	int	单位秒
customPort	自定义端口	[]customPort	公网访问自定义端口列表

customPort:

字段名	含义	类型	说明
localPort	原端口	int	自定义端口
type	端口类型	string	端口类型，http 或者 tcp
subDomain	访问域名	string	公网访问地址

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v2/app?page=1&pageSize=100' -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "appList": [
            {
                "appId": "548iag9wzvfxkk63-bam7jpt5",
                "appImageAuthor": "官方版",
                "appImageId": "PUBLIC_6",
                "appImageName": "ComfyUI",
                "appImageVersion": "v0.0.66",
                "billType": 3,
                "createdAt": 1734685267,
                "customName": "",
                "customPort": [],
                "errCode": 0,
                "expiredAt": 0,
                "gpuType": "NVIDIA-GEFORCE-RTX-4090",
                "groupId": "",
                "prePrice": 1.131,
                "price": 0.039,
                "regionId": 6,
                "runtime": 1716,
                "startedAt": 1734685267,
                "status": 300,
                "stoppedAt": 0,
                "systemDiskSize": 71680,
                "systemDiskSizeUsed": 24,
                "webUIAddress": ""
            },
            {
                "appId": "aagz63qkmhltsma1-eln150q2",
                "appImageAuthor": "官方版",
                "appImageId": "",
                "appImageName": "PyTorch",
                "appImageVersion": "PyTorch/2.0.1/3.10(ubuntu22.04)/11.7.1",
                "billType": 3,
                "createdAt": 1734421450,
                "customName": "",
                "customPort": [],
                "errCode": 0,
                "expiredAt": 1735159512,
                "gpuType": "NVIDIA-GEFORCE-RTX-4090",
                "groupId": "",
                "prePrice": 0,
                "price": 0.039,
                "regionId": 6,
                "runtime": 0,
                "startedAt": 0,
                "status": 800,
                "stoppedAt": 1734554712,
                "systemDiskSize": 71680,
                "systemDiskSizeUsed": 16,
                "webUIAddress": ""
            }
        ],
        "pagination": {
            "page": 1,
            "pageSize": 100,
            "total": 3
        }
    },
    "msg": "Success"
}

6、实例停用接口

接口地址：/api/v1/app/operate/shutdown/{appId}

接口描述：实例停用

请求方式：PUT

请求参数

无

curl 请求例子

curl -X PUT 'https://api-lab.onethingai.com/api/v1/app/operate/shutdown/ingr4j8rw3gtopnq-8kevdtua' -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code":0,
    "data": null,
    "msg": "Success"
}

7、实例启用接口

接口地址：/api/v1/app/operate/boot/{appId}

接口描述：实例开机

请求方式：PUT

请求参数

无

curl 请求例子

curl -X PUT 'https://api-lab.onethingai.com/api/v1/app/operate/boot/ingr4j8rw3gtopnq-8kevdtuz' -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code":0,
    "data": null,
    "msg": "Success"
}

8、实例卸载接口

接口地址：/api/v1/app/{appId}

接口描述：实例卸载

请求方式：DELETE

请求参数

无

curl 请求例子

curl -X DELETE 'https://api-lab.onethingai.com/api/v1/app/ingr4j8rw3gtopnq-8kevdtuz'  -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code":0,
    "data": null,
    "msg": "Success"
}

9、实例cpu使用率接口

接口地址：/api/v1/app/{appId}/monitor/cpuutil

接口描述：实例cpu使用率数据接口，只能查询近30分钟数据

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
startTime	开始时间	int	是	开始时间
endTime	结束时间	int	是	结束时间

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/app/548iag9wzvfxkk63-bam7jpt5/monitor/cpuutil?startTime=1734686115&endTime=1734687915'  -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "list": [
            {
                "category": "cpuutil",
                "time": 1734688001,
                "value": 0.399020540372
            },
            {
                "category": "cpuutil",
                "time": 1734688016,
                "value": 0.321672586274
            },
            {
                "category": "cpuutil",
                "time": 1734688031,
                "value": 0.321672586274
            },
            {
                "category": "cpuutil",
                "time": 1734688046,
                "value": 0.587348224677
            }
        ]
    },
    "msg": "Success"
}

10、实例gpumemory使用数据接口

接口地址：/api/v1/app/{appId}/monitor/gpumemory

接口描述：实例gpumemory使用数据接口，只能查询近30分钟数据，单位MB

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
startTime	开始时间	int	是	开始时间，
endTime	结束时间	int	是	结束时间

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/app/548iag9wzvfxkk63-bam7jpt5/monitor/gpumemory?startTime=1734686115&endTime=1734687915'  -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "list": [
            {
                "category": "gpumemory:0",
                "time": 1734688001,
                "value": 543
            },
            {
                "category": "gpumemory:0",
                "time": 1734688016,
                "value": 543
            },
            {
                "category": "gpumemory:0",
                "time": 1734688031,
                "value": 543
            },
            {
                "category": "gpumemory:0",
                "time": 1734688046,
                "value": 543
            }
        ]
    },
    "msg": "Success"
}

11、实例memory使用数据接口

接口地址：/api/v1/app/{appId}/monitor/memory

接口描述：实例memory使用数据接口，只能查询近30分钟数据，单位MB

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
startTime	开始时间	int	是	开始时间，
endTime	结束时间	int	是	结束时间

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/app/548iag9wzvfxkk63-bam7jpt5/monitor/memory?startTime=1734686115&endTime=1734687915'  -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "list": [
            {
                "category": "memory",
                "time": 1734688001,
                "value": 1881.55859375
            },
            {
                "category": "memory",
                "time": 1734688016,
                "value": 1882.578125
            },
            {
                "category": "memory",
                "time": 1734688031,
                "value": 1882.578125
            },
            {
                "category": "memory",
                "time": 1734688046,
                "value": 1882.58203125
            }
        ]
    },
    "msg": "Success"
}

12、实例gpu使用率接口

接口地址：/api/v1/app/{appId}/monitor/gpuutil

接口描述：实例gpu使用率数据接口，只能查询近30分钟数据

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
startTime	开始时间	int	是	开始时间，
endTime	结束时间	int	是	结束时间

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/app/548iag9wzvfxkk63-bam7jpt5/monitor/gpuutil?startTime=1734686115&endTime=1734687915'  -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "list": [
            {
                "category": "gpuutil:0",
                "time": 1734688001,
                "value": 0
            },
            {
                "category": "gpuutil:0",
                "time": 1734688016,
                "value": 0
            },
            {
                "category": "gpuutil:0",
                "time": 1734688031,
                "value": 0
            },
            {
                "category": "gpuutil:0",
                "time": 1734688046,
                "value": 0
            }
        ]
    },
    "msg": "Success"
}

13、用户余额查询接口

请求地址：/api/v1/account/wallet/detail

接口描述：获取用户余额列表

请求方式：GET

请求参数

无

主要返回字段说明

字段名	含义	类型	说明
availableBalance	可用余额	float64	可用余额等于余额减实例预扣金额，优先扣代金券
availableVoucherCash	可用代金券	float64	可用代金券等于代金券减实例预扣金额，优先扣代金券
consumeCashTotal	总消费	float64	总消费

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/account/wallet/detail' -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "msg": "Success",
    "data": {
      "availableBalance": 0.05,
      "availableVoucherCash": 72.93,
      "consumeCashTotal": 6,
    }
}

14、用户消费账单查询接口

请求地址：/api/v2/account/wallet/consume/query

接口描述：获取用户消费账单

请求方式：GET

请求参数

字段名	含义	类型	是否必填	说明
page	页数	int	是	页数
pageSize	每页大小	int	是	每页大小，0 < pageSize <= 100
appId	实例id	string	否	实例id
businessType	交易事件	int	否	交易事件，1：实例使用，2：镜像储存，3：文件存储，4：实例扩容

主要返回字段说明

字段名	含义	类型	说明
orderId	订单id	string	订单id
createdAt	扣费时间	int	扣费时间戳
appId	实例id	string	实例id
consumCash	消费金额	float64	消费金额
voucherDeductCash	代金券消费	float64	代金券消费
actualPayCash	实付金额	float64	实付金额
businessType	交易事件	Int	交易事件，1：实例使用，2：镜像储存，3：文件存储，4：实例扩容
billType	计费方式	Int	计费方式，1：包月，2：包天，3：按量
runtime	运行时长	int	运行时长，单位秒
event	扣费事件	string	扣费事件
totalDiscountPrice	打折金额	Float64	打折金额

curl 请求例子

curl 'https://api-lab.onethingai.com/api/v1/account/wallet/consume/query?page=2&pageSize=100' -H 'Authorization: Bearer {TOKEN}'

返回例子

{
    "code": 0,
    "data": {
        "orderList": [
            {
                "actualPayCash": 0.14,
                "appId": "",
                "billType": 0,
                "businessType": 5,
                "consumeCash": 0.16,
                "createdAt": 1734623959,
                "event": "",
                "orderId": "20241219235919001026297440",
                "runtime": 0,
                "totalDiscountPrice": 0,
                "voucherDeductCash": 0.02
            },
            {
                "actualPayCash": 0,
                "appId": "aagz63qkmhltsma1-eln150q2",
                "billType": 3,
                "businessType": 1,
                "consumeCash": 11.08,
                "createdAt": 1734554712,
                "event": "关机扣费",
                "orderId": "20241219044512001016056266",
                "runtime": 17112,
                "totalDiscountPrice": 0,
                "voucherDeductCash": 11.08
            }
        ],
        "pagination": {
            "total": 966,
            "page": 1,
            "pageSize": 2
        }
    },
    "msg": "Success"
}

提交反馈