OpenAPI 实例管理

本页介绍实例的创建、列表、详情、重命名和释放。请求均需携带 OpenAPI 鉴权 Header。

需重点关注

释放实例会删除实例容器及本地系统盘、数据盘。请先将重要数据保存到云磁盘、文件存储或镜像。释放接口成功受理后不可撤销。

接口列表

操作	方法	路径
创建实例	POST	`/api/instance/create`
查询实例列表	GET	`/api/instance/list`
查询实例详情	GET	`/api/instance/detail`
重命名实例	POST	`/api/instance/rename`
释放实例	POST	`/api/instance/release`

创建实例

根据实例规格和镜像创建一个独立实例。调用前应先查询实例规格和公共/私有镜像。

http

POST /api/instance/create
Content-Type: application/json

最小可用请求

下面两个示例均为按小时计费、不扩容数据盘、不挂载云磁盘或对象存储，并使用密码登录。

方式一：使用 spec_id + image_id + image_type。服务端根据规格 ID 和镜像 ID 获取规范的规格、镜像 URL 与镜像类型。

json

{
  "region": "cn-north-b",
  "payment_type": "Hourly",
  "spec_id": 12,
  "gpu_num": 1,
  "image_id": 100,
  "image_type": "public",
  "data_disk_expand_size": 0,
  "login_method": 2
}

方式二：使用 spec_type + image。服务端根据规格编码获取规格，并根据镜像 URL 中的仓库关键字判断镜像类型、反查镜像 ID。

json

{
  "region": "cn-north-b",
  "payment_type": "Hourly",
  "spec_type": "gpu-rtx4090-1",
  "gpu_num": 1,
  "image": "harbor-pro.damodel.net/model_library/pytorch:latest",
  "data_disk_expand_size": 0,
  "login_method": 2
}

最小请求中的字段说明：

字段	来源	含义
`region`	实例规格查询条件	实例所在区域；必须与所选规格可用区域一致
`payment_type`	调用方选择	计费方式；最小示例使用 `Hourly`，无需传购买时长
`spec_id`	`/api/spec/list` 的 `spec_id`	规格 ID；与 `spec_type` 至少传一个，二者同时存在时以该字段为准
`spec_type`	`/api/spec/list` 的 `spec_type`	规格编码；未传 `spec_id` 时使用该字段精确查询规格
`gpu_num`	调用方选择	GPU 数量；必须大于等于 1，且不能超过规格的 `max_gpu_count`
`image`	公共镜像的 `image_url`，或私有镜像的 `image_tag`	URL 模式；必须以 `harbor-pro.damodel.net/` 开头，包含 `model_library` 识别为公开镜像，包含 `user_private` 识别为私有镜像，并在数据库中精确校验
`image_id`	公共或私有镜像列表	ID 模式的镜像 ID，必须与 `image_type` 同时传入
`image_type`	根据镜像来源确定	ID 模式的镜像类型；公开镜像传 `"1"`/`"public"`，私有镜像传 `"2"`/`"private"`
`data_disk_expand_size`	调用方选择	本地数据盘额外扩容容量，单位 GB；不扩容也必须传 `0`
`login_method`	调用方选择	SSH 登录方式；`2` 为密码登录，适合不依赖密钥的最小请求

方式一对应的 curl 示例：

shell

curl -X POST "$DAMODEL_API/api/instance/create" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "region": "cn-north-b",
    "payment_type": "Hourly",
    "spec_id": 12,
    "gpu_num": 1,
    "image_id": 100,
    "image_type": "public",
    "data_disk_expand_size": 0,
    "login_method": 2
  }'

方式二对应的 curl 示例：

shell

curl -X POST "$DAMODEL_API/api/instance/create" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "region": "cn-north-b",
    "payment_type": "Hourly",
    "spec_type": "gpu-rtx4090-1",
    "gpu_num": 1,
    "image": "harbor-pro.damodel.net/model_library/pytorch:latest",
    "data_disk_expand_size": 0,
    "login_method": 2
  }'

提示

highest_cuda、gpu_name、gpu_mem、cpu_per_gpu、memory_per_gpu、sys_disk_size 和 data_disk_size 不需要在请求中传入；服务端会根据解析后的规格记录覆盖这些字段。仍建议每次创建前重新查询规格，不要长期硬编码规格信息。

完整字段说明

字段	类型	必填	说明
`region`	string	是	区域，例如 `cn-north-a`
`payment_type`	string	是	`Hourly`、`Daily`、`Weekly` 或 `Monthly`
`purchase_duration`	integer	条件必填	非 `Hourly` 时必须大于等于 1
`spec_id`	integer	条件必填	与 `spec_type` 至少传一个；非零时优先，并覆盖请求中的 `spec_type`
`spec_type`	string	条件必填	未传 `spec_id` 时必填；在当前 `region` 中精确匹配规格
`gpu_num`	integer	是	GPU 数量，不得超过规格的 `max_gpu_count`
`gpu_name`	string	否	兼容字段，服务端使用规格记录中的 GPU 型号覆盖
`gpu_mem`	integer	否	兼容字段，服务端使用规格记录中的显存覆盖
`cpu_per_gpu`	integer	否	兼容字段，服务端使用规格记录中的 CPU 核数覆盖
`memory_per_gpu`	integer	否	兼容字段，服务端使用规格记录中的内存覆盖
`sys_disk_size`	integer	否	兼容字段，服务端使用规格记录中的默认系统盘覆盖
`data_disk_size`	integer	否	兼容字段，服务端使用规格记录中的默认数据盘覆盖
`data_disk_expand_size`	integer	是	数据盘扩容大小，单位 GB
`data_disk_mount_path`	string	否	默认 `/root/damodel-tmp`；必须为合法绝对路径
`highest_cuda`	string	否	兼容字段，服务端忽略前端值并使用规格记录中的最高 CUDA
`image_id`	integer	条件必填	ID 模式下与 `image_type` 同时传入；完整 ID 组合优先于 `image`
`image`	string	条件必填	URL 模式下必填；必须以 `harbor-pro.damodel.net/` 开头、精确匹配镜像数据库，并包含 `model_library` 或 `user_private` 关键字
`image_type`	string	条件必填	ID 模式下与 `image_id` 同时传入；仅支持 `"1"`/`"public"` 和 `"2"`/`"private"`
`instance_alias`	string	否	实例名称
`instance_hostname`	string	否	最长 42 个字符，只能使用字母、数字和连字符，且首尾必须是字母或数字
`login_method`	integer	否	`1` SSH 密钥登录，`2` 密码登录
`ssh_pubkey_id`	integer	条件必填	`login_method=1` 时使用的密钥 ID
`ssh_pubkey_name`	string	条件必填	`login_method=1` 时使用的密钥名称
`external_ip`	string	否	绑定已申请的外网 IP
`auto_renew`	boolean	否	是否自动续费，默认 `false`
`exist_disks`	array	否	挂载已创建的云磁盘
`new_disks`	array	否	创建实例时同时创建云磁盘
`object_mounts`	array	否	挂载已配置的对象存储

单个实例的 exist_disks 与 new_disks 总数不能超过 8。

exist_disks 元素：

字段	类型	必填	说明
`id`	integer	是	云磁盘数据库 ID
`uid`	string	是	云磁盘 UID
`mount_path`	string	否	实例内挂载路径；为空时使用云磁盘默认路径
`release_with_instance`	integer	是	`1` 随实例释放，`0` 保留云磁盘

new_disks 元素：

字段	类型	必填	说明
`size_gb`	integer	是	容量，单位 GB
`spec_id`	integer	是	云磁盘规格 ID
`mount_path`	string	否	实例内挂载路径
`release_with_instance`	integer	是	`1` 随实例释放，`0` 保留云磁盘

完整请求示例

shell

curl -X POST "$DAMODEL_API/api/instance/create" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "region": "cn-north-a",
    "payment_type": "Hourly",
    "purchase_duration": 1,
    "instance_alias": "openapi-demo",
    "spec_id": 12,
    "spec_type": "gpu-rtx4090-1",
    "gpu_name": "NVIDIA-GeForce-RTX-4090",
    "gpu_mem": 24564,
    "gpu_num": 1,
    "cpu_per_gpu": 16,
    "memory_per_gpu": 64,
    "sys_disk_size": 30,
    "data_disk_size": 50,
    "data_disk_expand_size": 20,
    "highest_cuda": "12.4",
    "image_id": 100,
    "image": "harbor-pro.damodel.net/model_library/pytorch:latest",
    "image_type": "public",
    "login_method": 2,
    "auto_renew": false,
    "exist_disks": [],
    "new_disks": []
  }'

该完整示例同时包含 spec_id/spec_type 和 image/image_id/image_type，用于兼容现有前端请求。服务端实际以 spec_id 和完整的 image_id + image_type 组合为准，并覆盖其余重复字段。

输出

字段	类型	说明
`instance_id`	integer	实例数据库 ID
`instance_uid`	string	实例 UID，后续查询和操作使用此字段
`payment_type`	string	付费方式
`release_time`	integer	预计释放时间，Unix 秒级时间戳；按需实例可能为 0

json

{
  "result": {
    "instance_id": 12345,
    "instance_uid": "71dbf455sdf1",
    "payment_type": "Hourly",
    "release_time": 0
  },
  "response_metadata": {
    "request_id": "request-id",
    "trace_id": "trace-id",
    "action": "",
    "version": "",
    "service": "",
    "error": null
  }
}

创建成功表示任务已受理，不代表实例已经运行。请轮询实例详情，直到 status 为 Running；如果最终为 Failed，请保留 request_id 和实例 UID 联系技术支持。

创建错误

`code_n`	`code`	说明
100002	`InvalidParameter`	必填参数、购买周期、主机名、挂载路径不合法，规格/镜像选择器不完整，镜像 URL 不是 DAMODEL Harbor 地址，或镜像 URL 关键字无法唯一识别
100038	`BalanceNotEnough`	主账号余额不足
100049	`UserCanNotCreateInstance`	账号状态或风控状态不允许创建实例
160001	`ResourceInsufficient`	当前资源不足
160004	`NoMatchNode`	没有满足条件的节点
160014	`SpecNotExistOrDisable`	规格不存在、已禁用或已售罄
160015	`CreateInstanceFailedForNotCertified`	主账号未完成实名认证
160019	`FailedForInvalidImage`	镜像不存在、未就绪或无权限
160032	`CreateInstanceFailedCudaNotMatch`	镜像 CUDA 版本高于规格支持版本
180007	`MountCloudDiskFailed`	云磁盘挂载失败
180008	`ExceededCloudDiskMaxCount`	挂载云磁盘总数超过 8

查询实例列表

http

GET /api/instance/list

参数	位置	类型	必填	说明
`page`	Query	integer	是	页码，从 1 开始；传 `0` 时按服务当前规则返回
`page_size`	Query	integer	是	每页数量，`0` 表示返回全部
`query`	Query	string	否	按实例 UID 或实例名称搜索
`status`	Query	string	否	状态筛选，例如 `Creating`、`Running`、`Stopped`、`Released`、`Failed`

shell

curl "$DAMODEL_API/api/instance/list?page=1&page_size=20&status=Running" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

result 为分页对象，实例数组位于 result.data。常用实例字段如下：

字段	说明
`instance_uid` / `instance_alias`	实例 UID 和名称
`status`	实例状态
`region` / `capacity_type`	区域和容量类型
`gpu_name` / `gpu_num`	GPU 型号和数量
`spec_id` / `spec_type`	实例规格
`payment_type`	付费类型
`image_id` / `image_name` / `image_type`	当前镜像信息
`ssh_host` / `ssh_port`	SSH 地址和端口
`login_method` / `ssh_pubkey_name`	SSH 登录方式和密钥名称
`external_ip` / `internal_ip`	外网和内网 IP
`jupyter_url` / `jupyter_token`	JupyterLab 访问参数
`start_time` / `stop_time` / `release_time`	Unix 秒级时间戳

需重点关注

列表和详情可能返回 ssh_password、jupyter_token 等敏感字段。请勿写入日志、监控标签或错误上报内容。

查询实例详情

http

GET /api/instance/detail?instance_uid={instance_uid}

shell

curl "$DAMODEL_API/api/instance/detail?instance_uid=71dbf455sdf1" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

详情 result 除列表常用字段外，还包含：

字段	说明
`cpu_core` / `memory_size` / `gpu_memory`	CPU、内存和显存详情
`sys_disk_size` / `data_disk_size`	系统盘和数据盘容量，单位 GB
`cloud_disks`	挂载的云磁盘列表
`gpu_price` / `data_disk_price`	当前计费周期单价
`rent_deadline` / `release_time`	租期截止和释放时间
`services`	实例已开放的服务列表
`support_power_type`	`1` 支持开关机，`0` 不支持
`shutdown_status` / `shutdown_stage` / `shutdown_push_progress`	关机任务状态、阶段和镜像推送进度

实例不存在或不属于当前 API Key 时，通常返回 160003 InstanceNotExistOrNoPrivilege。

重命名实例

http

POST /api/instance/rename

shell

curl -X POST "$DAMODEL_API/api/instance/rename" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "instance_uid": "71dbf455sdf1",
    "name": "training-node-01"
  }'

成功时 result 为 null。常见错误为 100002 InvalidParameter、160003 InstanceNotExistOrNoPrivilege 和 100014 InternalError。

释放实例

http

POST /api/instance/release

shell

curl -X POST "$DAMODEL_API/api/instance/release" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{"instance_uid": "71dbf455sdf1"}'

成功时 result 为 null，表示释放任务已受理。可以继续查询实例列表，确认状态变为 Released。

`code_n`	`code`	说明
100002	`InvalidParameter`	`instance_uid` 缺失或格式错误
160003	`InstanceNotExistOrNoPrivilege`	实例不存在或无权限
160012	`InstanceCanNotBeReleased`	当前状态或付费类型不允许手动释放
160013	`InstanceNotExistOrAlreadyReleased`	实例不存在或已释放
100014	`InternalError`	释放任务提交失败

OpenAPI 实例管理 ​

接口列表 ​

创建实例 ​

最小可用请求 ​

完整字段说明 ​

完整请求示例 ​

输出 ​

创建错误 ​

查询实例列表 ​

查询实例详情 ​

重命名实例 ​

释放实例 ​

OpenAPI 实例管理

接口列表

创建实例

最小可用请求

完整字段说明

完整请求示例

输出

创建错误

查询实例列表

查询实例详情

重命名实例

释放实例