# LibLib AI API UUID 匹配规则完整指南

> 基于 output.md 深度分析整理
> 最后更新：2026-03-23

## 目录
1. [核心匹配原则](#核心匹配原则)
2. [模板 UUID 列表](#模板-uuid-列表)
3. [Checkpoint ID 列表](#checkpoint-id-列表)
4. [ControlNet 模型完整列表](#controlnet-模型完整列表)
5. [匹配规则详解](#匹配规则详解)
6. [常见错误和解决方案](#常见错误和解决方案)
7. [推荐组合方案](#推荐组合方案)

---

## 核心匹配原则

### BaseType 三角匹配规则

```
Template baseType ← → Checkpoint baseType ← → ControlNet baseType
```

**关键要点**：
- Template、Checkpoint、ControlNet 必须使用**相同的 baseType**
- 不匹配会导致错误：`Cn模型baseType不匹配`
- 支持的 baseType：`F.1`、`XL`、`1.5`

---

## 模板 UUID 列表

### 1. 自定义模型模板（推荐）

| 模板名称 | Template UUID | 基础算法类型 | 适用场景 | 支持功能 |
|---------|---------------|-----------|--------|---------|
| 1.5和XL文生图 | `e10adc3949ba59abbe56e057f20f883e` | 1.5/XL | 文生图 | ControlNet, LoRA, HiresFix |
| 1.5和XL图生图 | `9c7d531dc75f476aa833b3d452b8f7ad` | 1.5/XL | 图生图 | ControlNet, LoRA, 蒙版重绘 |

### 2. F.1 系列模板

| 模板名称 | Template UUID | 基础算法类型 | 适用场景 |
|---------|---------------|-----------|--------|
| F.1文生图 | `6f7c4652458d4802969f8d089cf5b91f` | F.1 | 文生图 |
| F.1图生图 | `63b72710c9574457ba303d9d9b8df8bd` | F.1 | 图生图 |

### 3. 专用模板

| 模板名称 | Template UUID | 用途 |
|---------|---------------|------|
| Controlnet局部重绘 | `b689de89e8c9407a874acd415b3aa126` | 局部重绘 |
| 图生图局部重绘 | `74509e1b072a4c45a7f1843a963c8462` | 局部重绘 |
| InstantID人像换脸 | `7d888009f81d4252a7c458c874cd017f` | 人像换脸 |

---

## Checkpoint ID 列表

| Checkpoint 名称 | Checkpoint UUID | 基础算法类型 | 说明 |
|----------------|-----------------|-----------|------|
| SD 1.5 官方底模 | `6320087784014d5f850259e8f49890a1` | 1.5 | 推荐用于 1.5 系列 |
| 其他底模 | `0ea388c7eb854be3ba3c6f65aac6bfd3` | 待确认 | 需验证 baseType |

---

## ControlNet 模型完整列表

### 1. 线稿类

#### 1.1 Canny（硬边缘）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11p_sd15_canny | 1.5 | `7d917ec7e55c5805db737d3b493c91ce` | 1 |
| t2iadapter_canny_sd14v1 | 1.5 | `a2c41c4e97944f3aa71f913bdc45b1ca` | 1 |
| t2iadapter_canny_sd15v2 | 1.5 | `c04144bcf017232483181cd8607097c2` | 1 |
| diffusers_xl_canny_full | XL | `56de5edadb6f2891aff05ff078dc0470` | 1 |
| diffusers_xl_canny_mid | XL | `efb97e9d8c237573298c3a5a7869b89c` | 1 |
| diffusers_xl_canny_small | XL | `dccde738064e9748f93b48ec5868968e` | 1 |
| xinsir_controlnet-canny-sdxl_V2 | XL | `b6806516962f4e1599a93ac4483c3d23` | 1 |
| XLabs-flux-canny-controlnet_v3 | F.1 | `017997cd6ba44c4dbe8f60e0a26cd0df` | 1 |

**Canny 参数配置**：
```json
{
  "preprocessor": 1,
  "annotationParameters": {
    "canny": {
      "preprocessorResolution": 512,
      "lowThreshold": 100,
      "highThreshold": 200
    }
  }
}
```

#### 1.2 SoftEdge（软边缘）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11p_sd15_softedge | 1.5 | `0929722d9047ec6498a50ff5d1081629` | 5 |
| sargezt_xl_softedge | XL | `dda1a0c480bfab9833d9d9a1e4a71fff` | 5 |
| XLabs-flux-hed-controlnet_v3 | F.1 | `6c4d620df3644514903b8189735c6ae9` | 5 |

#### 1.3 Lineart（线稿）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11p_sd15_lineart | 1.5 | `b06dfbd1a61c35e933d9f8caa8a0e031` | 29 |
| control_v11p_sd15s2_lineart_anime | 1.5 | `c263e039c57b8a958ee0a936039af654` | 31 |
| t2i-adapter_diffusers_xl_lineart | XL | `a0f01da42bf48b0ba02c86b6c26b5699` | 29 |

### 2. 空间关系类

#### 2.1 Depth（深度图）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11f1p_sd15_depth | 1.5 | `cf63d214734760dcdc108b1bd094921b` | 3 |
| xinsir_controlnet_depth_sdxl_1.0 | XL | `6349e9dae8814084bd9c1585d335c24c` | 3 |
| XLabs-flux-depth-controlnet_v3 | F.1 | `0cc4e6b8206b44cdab51e30fb8b9c328` | 3 |
| Flux.1-dev-Controlnet-Depth | F.1 | `64dd7a6c714f4512a4500f6a01b016b7` | 3 |

**Depth 参数配置**：
```json
{
  "preprocessor": 3,
  "annotationParameters": {
    "depth_leres": {
      "preprocessorResolution": 512,
      "removeNear": 0,
      "removeBg": 0
    }
  }
}
```

#### 2.2 Normal（法线图）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11p_sd15_normalbae | 1.5 | `9a85fdca18a8b58b2fb2ff13ab339be4` | 10 |
| Flux.1-dev-Controlnet-Surface-Normal | F.1 | `e51fdccdf3b8417aab246bde40b5f360` | 10 |

### 3. 姿态类

#### 3.1 OpenPose（姿态检测）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11p_sd15_openpose | 1.5 | `b46dd34ef9c2fe189446599d62516cbf` | 11 |
| xinsir_controlnet-openpose-sdxl-1.0 | XL | `23ef8ab803d64288afdb7106b8967a55` | 11 |
| F.1-ControlNet-Pose-V1 | F.1 | `7c6d889cb9c04b78858d8fece80f9f85` | 11 |

### 4. 画面参考类

#### 4.1 Tile/Blur（分块/超分）

| 模型名称 | 基础算法 | 模型UUID | 预处理器值 |
|---------|--------|---------|----------|
| control_v11f1e_sd15_tile | 1.5 | `37e42c6bdb6fab4c24a662100f20f722` | 14 |
| xinsir_controlnet_tile_sdxl_1.0 | XL | `0f47ef6d4f4b40afab8b290c98baac0e` | 14 |
| Flux.1-dev-Controlnet-Upscaler | F.1 | `a696b5bdadc740119fd76505b33d6898` | 14 |

### 5. 风格迁移类

#### 5.1 IP-Adapter

| 模型名称 | 基础算法 | 模型UUID | 用途 |
|---------|--------|---------|------|
| ip-adapter_sd15 | 1.5 | `18801062fe4289dd0a984e69de9f9e7c` | 风格迁移 |
| ip-adapter_sd15_plus | 1.5 | `ad4bd9b4b05c4ac8faf7f81d9fdcadc8` | 风格迁移增强 |
| ip-adapter_xl | XL | `8ea2538fdd7dcdea52b2da6b5151f875` | 风格迁移 |
| InstantX-F.1-dev-IP-Adapter | F.1 | `c6ed70879cf011ef96d600163e37ec70` | 风格迁移 |

---

## 匹配规则详解

### 规则 1：BaseType 必须一致

```python
# ✅ 正确示例（都是 1.5）
{
  "templateUuid": "e10adc3949ba59abbe56e057f20f883e",  # 1.5/XL
  "generateParams": {
    "checkPointId": "6320087784014d5f850259e8f49890a1",  # 1.5
    "controlNet": [{
      "model": "7d917ec7e55c5805db737d3b493c91ce"  # 1.5 Canny
    }]
  }
}

# ❌ 错误示例（baseType 不匹配）
{
  "templateUuid": "e10adc3949ba59abbe56e057f20f883e",  # 1.5/XL
  "generateParams": {
    "checkPointId": "6320087784014d5f850259e8f49890a1",  # 1.5
    "controlNet": [{
      "model": "017997cd6ba44c4dbe8f60e0a26cd0df"  # F.1 Canny ❌
    }]
  }
}
```

### 规则 2：预处理器参数必须匹配

| ControlNet 类型 | 预处理器 | 预处理器值 | 参数配置 |
|----------------|--------|----------|--------|
| Canny | canny | 1 | lowThreshold, highThreshold |
| Depth | depth_leres | 3 | removeNear, removeBg |
| OpenPose | openpose | 11 | 无额外参数 |
| Tile | tile_resample | 14 | 无额外参数 |

### 规则 3：ControlNet 参数类型

**重要**：以下参数必须是**整数**，不能是布尔值：
- `pixelPerfect`: 1 或 0（不能是 true/false）
- `controlMode`: 0, 1, 2（不能是 false/true）
- `resizeMode`: 0, 1, 2（不能是 false/true）

```python
# ✅ 正确
"pixelPerfect": 1,
"controlMode": 0,
"resizeMode": 1

# ❌ 错误
"pixelPerfect": True,  # 会报错：参数无效
"controlMode": False,
"resizeMode": True
```

---

## 常见错误和解决方案

### 错误 1：Cn模型baseType不匹配

**错误信息**：
```json
{
  "code": 100050,
  "msg": "生图参数未通过参数完整度校验，请检查参数配置: [1002011]Cn模型baseType不匹配;"
}
```

**原因**：ControlNet 模型和 Checkpoint 底模的基础算法类型不一致

**解决方案**：
1. 检查 Checkpoint ID 的 baseType
2. 选择相同 baseType 的 ControlNet 模型
3. 参考上面的模型列表，确保三者匹配

### 错误 2：参数无效 pixelPerfect

**错误信息**：
```json
{
  "code": 100000,
  "msg": "参数无效: controlNet[0].pixelPerfect"
}
```

**原因**：使用了布尔值而不是整数

**解决方案**：
```python
# 改为整数
"pixelPerfect": 1,  # 不是 True
"controlMode": 0,   # 不是 False
"resizeMode": 1     # 不是 True
```

### 错误 3：内部服务错误

**错误信息**：
```json
{
  "code": 200000,
  "msg": "内部服务错误"
}
```

**可能原因**：
1. 图片上传失败（OSS 返回 403）
2. LibLib 服务维护中
3. 参数配置错误（但未被前置校验捕获）

**解决方案**：
1. 确认图片 URL 可访问
2. 等待服务恢复
3. 检查所有参数配置

---

## 推荐组合方案

### 方案 1：精准线稿生成（1.5）

```json
{
  "templateUuid": "e10adc3949ba59abbe56e057f20f883e",
  "generateParams": {
    "checkPointId": "6320087784014d5f850259e8f49890a1",
    "prompt": "masterpiece, best quality, detailed",
    "width": 512,
    "height": 512,
    "controlNet": [{
      "unitOrder": 1,
      "sourceImage": "图片URL",
      "model": "7d917ec7e55c5805db737d3b493c91ce",  # Canny 1.5
      "preprocessor": 1,
      "annotationParameters": {
        "canny": {
          "preprocessorResolution": 512,
          "lowThreshold": 100,
          "highThreshold": 200
        }
      },
      "controlWeight": 1,
      "startingControlStep": 0,
      "endingControlStep": 1,
      "pixelPerfect": 1,
      "controlMode": 0,
      "resizeMode": 1
    }]
  }
}
```

### 方案 2：深度图 + 姿态控制（XL）

```json
{
  "templateUuid": "e10adc3949ba59abbe56e057f20f883e",
  "generateParams": {
    "checkPointId": "0ea388c7eb854be3ba3c6f65aac6bfd3",
    "controlNet": [
      {
        "unitOrder": 1,
        "model": "6349e9dae8814084bd9c1585d335c24c",  # Depth XL
        "preprocessor": 3,
        "controlWeight": 0.8
      },
      {
        "unitOrder": 2,
        "model": "23ef8ab803d64288afdb7106b8967a55",  # OpenPose XL
        "preprocessor": 11,
        "controlWeight": 1.0
      }
    ]
  }
}
```

### 方案 3：超分辨率增强（F.1）

```json
{
  "templateUuid": "6f7c4652458d4802969f8d089cf5b91f",
  "generateParams": {
    "width": 1024,
    "height": 1024,
    "controlNet": [{
      "model": "a696b5bdadc740119fd76505b33d6898",  # Tile F.1
      "preprocessor": 14,
      "controlWeight": 0.6
    }]
  }
}
```

---

## 快速查询表

### BaseType 对应关系

| BaseType | Template UUID | Checkpoint ID | ControlNet 前缀 |
|---------|---------------|---------------|----------------|
| 1.5 | e10adc3949ba59abbe56e057f20f883e | 6320087784014d5f850259e8f49890a1 | control_v11p_sd15_*, t2iadapter_* |
| XL | e10adc3949ba59abbe56e057f20f883e | 0ea388c7eb854be3ba3c6f65aac6bfd3 | *_xl_*, xinsir_*, sai_xl_* |
| F.1 | 6f7c4652458d4802969f8d089cf5b91f | 待定 | XLabs-flux-*, F.1-*, Flux.1-* |

### 预处理器枚举值

| 预处理器名称 | 枚举值 | 用途 |
|------------|-------|------|
| canny | 1 | 硬边缘检测 |
| depth_leres | 3 | 深度图（LeReS） |
| depth_zoe | 4 | 深度图（ZoeDepth） |
| hed | 5 | 软边缘检测 |
| mlsd | 8 | 直线检测 |
| seg_ufade20k | 9 | 语义分割 |
| normal_bae | 10 | 法线图 |
| openpose | 11 | 姿态检测 |
| densepose | 12 | 密集姿态 |
| tile_resample | 14 | 分块/超分 |
| lineart_realistic | 29 | 写实线稿 |
| lineart_anime | 31 | 动漫线稿 |

---

## 参考资源

- **原始文档**：`C:\Users\11304\gitlab\cybertogether\tool_agent\output.md`
- **测试脚本**：`tests/test_lib.py`
- **任务书**：`tests/tasks/liblibai_controlnet.json`

---

**最后更新**：2026-03-23
**维护者**：Tool Agent Team