# 模型库接口文档 (Token认证)

## 认证说明

所有接口支持 **API Token认证**，通过请求头传递：

```
X-API-Key: <your_api_token>
```

API Token 从大模型平台用户端 账号设置->账号中心(基础信息)获取。

---

## 1. 分页查询模型库列表

**接口路径**: `POST /user/modellibrary/list`

**接口描述**: 分页查询模型库列表，只返回启用状态的项目

### 请求头

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-API-Key | String | 是 | API Token |
| Content-Type | String | 是 | application/json |

### 请求参数

```json
{
    "pageNum": 1,           // 页码，从1开始，默认1
    "pageSize": 10,         // 每页记录数，默认10
    "search": "",           // 搜索关键词(模型名称模糊搜索)，可选
    "status": 1,            // 项目状态(1启用 2禁用)，可选
    "labelIds": ["id1", "id2"]  // 标签ID列表，可选
}
```

### 响应参数

```json
{
    "code": 200,            // 状态码，200成功
    "message": "操作成功",   // 提示信息
    "data": {
        "list": [
            {
                "id": "项目主键ID",
                "systemUserId": "用户ID",
                "gitlabProjectId": 123,
                "modelName": "模型名称",
                "modelId": "模型ID",
                "licenseTemplate": "授权模板",
                "publicFlag": 1,        // 1公开 0私有
                "projectOwner": "拥有者",
                "projectWebUrl": "项目Web地址",
                "status": 1,            // 1启用 2禁用
                "httpUrlToRepo": "HTTP克隆地址",
                "sshUrlToRepo": "SSH克隆地址",
                "createTime": "2026-01-01T00:00:00",
                "downloadCount": 100,   // 下载次数
                "branchCount": 5,       // 分支数量
                "projectPath": "namespace/path",
                "labels": [             // 关联标签
                    {
                        "labelName": "标签名称",
                        "labelLevel": "标签级别",
                        "iconFile": "图标文件路径"
                    }
                ]
            }
        ],
        "total": 100         // 总记录数
    }
}
```

---

## 2. 获取分支列表

**接口路径**: `POST /user/modellibrary/branches`

**接口描述**: 获取指定项目的分支和标签列表

### 请求头

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-API-Key | String | 是 | API Token |
| Content-Type | String | 是 | application/json |

### 请求参数

```json
{
    "projectId": "项目ID"    // 必填
}
```

### 响应参数

```json
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "branches": [
            {
                "name": "分支名称",
                "commit": {
                    "id": "提交ID",
                    "message": "提交信息",
                    "authorName": "作者"
                }
            }
        ],
        "tags": [
            {
                "name": "标签名称",
                "commit": {
                    "id": "提交ID",
                    "message": "提交信息"
                }
            }
        ]
    }
}
```

---

## 3. 创建模型库项目

**接口路径**: `POST /user/modellibrary/create`

**接口描述**: 创建新的模型库项目

### 请求头

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-API-Key | String | 是 | API Token |
| Content-Type | String | 是 | application/json |

### 请求参数

```json
{
    "modelName": "my-model",     // 必填，模型名称
                                 // 规则: 2-100字符，首尾字母或数字，中间只能包含_.-符号
    "modelId": "model-001",      // 必填，模型ID
    "licenseLabelId": "license-id", // 必填，授权模板ID
    "publicFlag": 1              // 必填，是否公开(1公开 0私有)
}
```

### modelName 校验规则

- 长度：2-100字符
- 首尾必须是字母或数字
- 中间只能包含 `_.-` 符号
- 正则表达式: `^[a-zA-Z0-9][a-zA-Z0-9_.\-]{0,98}[a-zA-Z0-9]$`

### 响应参数

```json
{
    "code": 200,
    "message": "操作成功",
    "data": null
}
```

---

## 错误响应

### 认证失败

```json
{
    "code": 500,
    "message": "Token认证失败，请检查token是否有效",
    "data": null
}
```

### 参数校验失败

```json
{
    "code": 500,
    "message": "模型名称不能为空",
    "data": null
}
```