# 获取定制模型列表

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListCustomModels&Version=2024-01-01`

查询当前账号下的定制模型列表，支持按模型 ID、名称、标签和项目等条件筛选，并可分页与排序返回结果。

> **说明：注意**
>
> 本接口仅返回当前账号下可见的定制模型，跨项目查询需指定正确的 ProjectName。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**Filter** `object` | 定制模型筛选条件

待查询定制模型的筛选条件。

**Ids** `string[]` | 定制模型 ID 列表

`Filter.Ids`

定制模型 ID 数组，精确匹配。

**Name** `string` | 定制模型名称

`Filter.Name`

定制模型名称，模糊匹配。

**PageNumber** `integer` `默认值 1` | 起始页码

分页查询时的起始页码，从 1 开始。

**最小值**：`1`

**PageSize** `integer` `默认值 10` | 每页记录数

分页查询时每页显示的记录数。

**取值范围**：`[1, 100]`

**ProjectName** `string` `默认值 default` | 项目名称

资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。

**SortBy** `string` `默认值 CreateTime` | 排序指标

指定排序指标。可选值：`CreateTime`、`UpdateTime`。

**SortOrder** `string` `默认值 Desc` | 排序顺序

指定排序顺序。可选值：`Asc`、`Desc`。

**TagFilters** `object[]` | 标签筛选条件

基于绑定标签的筛选条件。

**Key** `string` `必选` | 标签键

`TagFilters.Key`

**Values** `string[]` | 标签值列表

`TagFilters.Values`

## 响应参数

**Items** `object[]` | 定制模型列表

本页返回的定制模型列表

**CreateTime** `string` | 创建时间

`Items.CreateTime`

定制模型创建时间，RFC 3339 格式。

**CustomizationType** `string` | 定制类型

`Items.CustomizationType`

定制类型。
- `FinetuneSft`：SFT 精调。
- `FinetuneLoRA`：LoRA 精调。
- `Pretrain`：预训练。

**FoundationModel** `object` | 基础模型引用

`Items.FoundationModel`

定制模型所基于的基础模型引用。

**ModelVersion** `string` | 基础模型版本

`Items.FoundationModel.ModelVersion`

**Name** `string` | 基础模型名称

`Items.FoundationModel.Name`

**HyperParameters** `object[]` | 超参列表

`Items.HyperParameters`

定制模型的超参列表。

**Name** `string` | 超参数名

`Items.HyperParameters.Name`

超参数的参数名

**Value** `string` | 超参数值

`Items.HyperParameters.Value`

超参数的参数值

**Id** `string` | 定制模型 ID

`Items.Id`

**Name** `string` | 定制模型名称

`Items.Name`

**ProjectName** `string` | 项目名称

`Items.ProjectName`

定制模型所属的项目名称。

**SourceType** `string` | 来源类型

`Items.SourceType`

定制模型的来源类型。
- `Customization`：精调模型。
- `Import`：导入模型。

**Status** `string` | 定制模型状态

`Items.Status`

定制模型的状态。取值包括 `Ready`（就绪）等。

**Tags** `object[]` | 绑定的标签

`Items.Tags`

定制模型绑定的标签列表。

**Key** `string` | 标签键

`Items.Tags.Key`

**Value** `string` | 标签值

`Items.Tags.Value`

**UpdateTime** `string` | 更新时间

`Items.UpdateTime`

定制模型更新时间，RFC 3339 格式。

**Description** `string` | 定制模型描述

`Items.Description`

**LoraBaseModelAvailable** `boolean` | LoRA 基础模型是否可用

`Items.LoraBaseModelAvailable`

如果当前定制模型是基于某共享模型增量训练得到的，该字段表示来源共享模型是否仍然有效。

**ModelCustomizationJobId** `string` | 调优任务 ID

`Items.ModelCustomizationJobId`

模型调优任务 ID。

**SourceModelAvailable** `boolean` | 源模型是否可用

`Items.SourceModelAvailable`

如果当前定制模型是基于全量 SFT 模型增量精调得到的，该字段表示全量 SFT 模型是否仍然有效。

**PageNumber** `integer` | 起始页码

分页查询时的起始页码。

**PageSize** `integer` | 每页记录数

分页查询时每页显示的记录数。

**TotalCount** `integer` | 定制模型总数

符合查询条件的定制模型总数


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListCustomModels&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
  "PageNumber": 1,
  "PageSize": 1,
  "Filter": {
    "Ids": [
      "vrYVig"
    ],
    "Name": "aThQ2SZH"
  },
  "TagFilters": [
    {
      "Key": "8mYbP7pN",
      "Values": [
        "8bS"
      ]
    }
  ],
  "ProjectName": "default",
  "SortBy": "CreateTime",
  "SortOrder": "Desc"
}
'
```

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "20240514210517123075045154E335F9",
    "Action": "ListCustomModels",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 10,
    "Items": [
      {
        "Id": "cm-20240514210342-9k4hn",
        "Name": "自定义模型-电商图像生成",
        "Description": "基于 doubao-seed-2-0-pro 的 LoRA 精调模型 · 用于电商场景图像生成",
        "SourceType": "Customization",
        "ModelCustomizationJobId": "mcj-20240401114541-5gzd8",
        "CustomizationType": "FinetuneLoRA",
        "Status": "Ready",
        "HyperParameters": [
          {
            "Name": "learning_rate",
            "Value": "0.0001"
          }
        ],
        "FoundationModel": {
          "Name": "doubao-seed-2-0-pro",
          "ModelVersion": "260215"
        },
        "Tags": [
          {
            "Key": "env",
            "Value": "stg"
          }
        ],
        "ProjectName": "default",
        "CreateTime": "2024-04-01T11:54:41Z",
        "UpdateTime": "2024-05-14T20:59:45Z"
      }
    ]
  }
}
```