OpenAPI 镜像管理

本页介绍公共镜像查询，以及私有镜像的保存、列表、重命名和删除。请求均需携带 OpenAPI 鉴权 Header。

私有镜像通过“将实例系统盘保存为镜像”创建。保存操作异步执行，接口成功返回后还需要轮询私有镜像状态。

接口列表

操作	方法	路径
查询公共镜像	GET	`/api/image/publics_v2`
查询私有镜像	GET	`/api/image/privates`
保存实例为私有镜像	POST	`/api/instance/save_image_v2`
重命名私有镜像	PUT	`/api/image/update`
删除私有镜像	DELETE	`/api/image/delete/{image_id}`

查询公共镜像

查询可用于创建实例的基础镜像。返回的 id、image_url 和 CUDA/软件信息用于构造创建实例请求。

http

GET /api/image/publics_v2

参数	位置	类型	必填	说明
`label`	Query	string	否	单个标签，例如 `Pytorch`；不支持一次传多个标签
`name`	Query	string	否	按镜像名称、软件名称或软件版本模糊搜索

shell

curl "$DAMODEL_API/api/image/publics_v2?label=Pytorch&name=CUDA" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

result 是镜像数组。

字段	类型	说明
`id`	integer	镜像 ID，创建实例时作为 `image_id`
`name`	string	镜像显示名称
`image_url`	string	镜像完整地址，创建实例时作为 `image`
`description`	string	镜像说明
`softwares`	string[]	预装软件
`labels`	string[]	镜像标签
`size`	string	镜像大小展示值
`document_url`	string	使用文档地址
`icon`	string	镜像图标地址
`create_time` / `update_time`	integer	Unix 秒级时间戳

创建实例时，公共镜像参数示例：

json

{
  "image_id": 100,
  "image": "harbor-pro.damodel.net/model_library/pytorch:latest",
  "image_type": "public"
}

公开镜像的 image_type 也可以传字符串 "1"，与 "public" 等价。

可能的错误

`code_n`	`code`	说明
100002	`InvalidParameter`	标签或搜索参数不合法
100014	`InternalError`	公共镜像服务不可用

查询私有镜像

http

GET /api/image/privates

参数	位置	类型	必填	说明
`page`	Query	integer	是	页码
`page_size`	Query	integer	是	每页数量
`image_name`	Query	string	否	按镜像名称搜索
`image_status`	Query	integer	否	`0` 创建中，`1` 已就绪

shell

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

私有镜像数组位于 result.data。

字段	类型	说明
`image_id`	integer	镜像 ID，更新、删除和创建实例时使用
`image_uuid`	string	镜像 UUID
`image_name`	string	镜像名称
`image_tag`	string	镜像完整地址，创建实例时作为 `image`
`image_status`	integer	`0` 创建中，`1` 已就绪
`push_progress`	integer	推送进度，范围 0～100
`image_size`	number	镜像大小
`original_image`	string	创建该镜像时实例使用的原始镜像
`region`	string	镜像所属区域
`create_time` / `updated_at`	integer	Unix 秒级时间戳
`upperdir_files` / `upperdir_bytes`	integer	实例可写层文件数量和字节数

创建实例时，私有镜像参数示例：

json

{
  "image_id": 456,
  "image": "harbor-pro.damodel.net/user_private/user-image:v1",
  "image_type": "private"
}

私有镜像的 image_type 也可以传字符串 "2"，与 "private" 等价。

image_type 仅接受 "1"、"2"、"public"、"private"；其他值会返回 100002 InvalidParameter。

创建实例时也可以只传完整 image URL，不传 image_id 和 image_type。URL 必须以 harbor-pro.damodel.net/ 开头；包含 model_library 时识别为公开镜像，包含 user_private 时识别为私有镜像。URL 还必须在镜像数据库中精确匹配，并通过启用状态或私有镜像权限/就绪状态校验。

保存实例为私有镜像

将当前实例系统盘异步保存为私有镜像。实例必须存在且属于当前 API Key 可操作的账号。

http

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

字段	类型	必填	说明
`instance_uid`	string	是	要保存的实例 UID
`image_name`	string	是	新镜像名称，同一账号下不能重复

shell

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

输出

字段	类型	说明
`image_id`	integer	新创建的私有镜像 ID
`image_tag`	string	镜像完整地址

json

{
  "result": {
    "image_id": 456,
    "image_tag": "harbor-pro.damodel.net/user_private/user-image:v1"
  },
  "response_metadata": {
    "request_id": "request-id",
    "trace_id": "trace-id",
    "action": "",
    "version": "",
    "service": "",
    "error": null
  }
}

接口返回后，通过私有镜像列表查询该 image_id：

image_status=0：仍在创建；可以查看 push_progress。
image_status=1：镜像已就绪，可以用于创建实例。

需关注

保存镜像会产生镜像存储费用。不要在已有镜像上频繁制作新镜像，也不要把大数据文件写入系统盘镜像。

保存镜像错误

`code_n`	`code`	说明
100002	`InvalidParameter`	实例 UID 或镜像名称缺失
100038	`BalanceNotEnough`	主账号余额不足
130001	`ImageNameExisted`	镜像名称已存在
130002	`ImageUploading`	已有镜像正在创建
130003	`ImageSaveBusy`	保存请求过于频繁
130008	`ImageSaveCountExceeded`	当日保存次数已达上限
160003	`InstanceNotExistOrNoPrivilege`	实例不存在或无操作权限
100014	`InternalError`	镜像任务提交失败

重命名私有镜像

http

PUT /api/image/update

shell

curl -X PUT "$DAMODEL_API/api/image/update" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "image_id": 456,
    "image_name": "pytorch-training-v2"
  }'

成功时 result 为 null。

删除私有镜像

http

DELETE /api/image/delete/{image_id}

shell

curl -X DELETE "$DAMODEL_API/api/image/delete/456" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

成功时 result 为 null。

需重点关注

删除镜像不可撤销。若镜像正在被创建中的实例使用，服务端会拒绝删除。

更新和删除常见错误

`code_n`	`code`	说明
100002	`InvalidParameter`	镜像 ID 或镜像名称不合法
130001	`ImageNameExisted`	新镜像名称已存在
130004	`ImageNoPrivilege`	当前 API Key 无镜像操作权限
130005	`ImageUsedByInstance`	镜像正在被创建中的实例使用，不能删除
130006	`ImageNotFound`	镜像不存在或已删除
100014	`InternalError`	镜像服务调用失败

OpenAPI 镜像管理 ​

接口列表 ​

查询公共镜像 ​

可能的错误 ​

查询私有镜像 ​

保存实例为私有镜像 ​

输出 ​

保存镜像错误 ​

重命名私有镜像 ​

删除私有镜像 ​

更新和删除常见错误 ​

OpenAPI 镜像管理

接口列表

查询公共镜像

可能的错误

查询私有镜像

保存实例为私有镜像

输出

保存镜像错误

重命名私有镜像

删除私有镜像

更新和删除常见错误