# API 参数与 Capabilities 映射关系

**版本**: v1.0  
**日期**: 2026-02-13  
**目的**: 明确前端 API 参数与数据库 capabilities 配置的对应关系

---

## 📋 参数分类

### 1. 简单模式参数（Unified Parameters）

这些参数由**前端传递**，经过**适配器转换**为模型特定参数：

| 前端参数 | 类型 | 值域 | 转换目标 | 说明 |
|---------|------|------|---------|------|
| `resolution` (图片) | string | "512", "1024", "2048", "4096" | `width`, `height`, `size` | 短边像素值 |
| `resolution` (视频) | string | "480p", "720p", "1080p", "2k", "4k" | `width`, `height`, `size` | 分辨率档位 |
| `aspectRatio` | string | "1:1", "4:3", "16:9", "9:16" | `width`, `height`, `aspect_ratio` | 宽高比 |
| `quality` | string | "low", "medium", "high" | `quality`, `rendering_speed` | 质量档位 |

**检测条件**：
- **图片生成**：`resolution` AND `aspectRatio` 存在
- **视频生成**：`resolution` AND `aspectRatio` 存在

---

### 2. 高级模式参数（Model-Specific Parameters）

这些参数直接传递给模型，**不经过适配器**：

#### 图片模型参数

| API 参数 | capabilities 字段 | 类型 | 说明 | 示例值 |
|---------|------------------|------|------|--------|
| `width` | `size` | integer | 宽度（像素） | 1024 |
| `height` | `size` | integer | 高度（像素） | 1024 |
| `style` | - | string | 风格（前端自定义） | "realistic" |
| `outputFormat` | `output_format` | string | 输出格式 | "png", "jpeg", "webp" |
| `inputFidelity` | `input_fidelity` | string | 输入保真度（OpenAI） | "high", "low" |
| `moderation` | `moderation` | string | 内容审核（OpenAI） | "auto", "low" |
| `watermark` | `watermark` | boolean | 水印（Qwen/Doubao） | true, false |
| `seed` | `seed` | integer | 随机种子 | 0-2147483647 |
| `numImages` | `n` | integer | 生成数量 | 1-10 |
| `safetyTolerance` | `safety_tolerance` | integer | 安全容忍度（Flux） | 0-6 |
| `raw` | `raw` | boolean | 原始模式（Flux） | true, false |
| `guidance` | `guidance` | float | 引导强度（iRAG） | 0.0-10.0 |
| `renderingSpeed` | `rendering_speed` | string | 渲染速度（Ideogram） | "QUALITY", "FAST" |
| `sequentialImageGeneration` | `sequential_image_generation` | string | 连续生成（Doubao） | "auto", "disabled" |

#### 视频模型参数

| API 参数 | capabilities 字段 | 类型 | 说明 | 示例值 |
|---------|------------------|------|------|--------|
| `width` | `size` | integer | 宽度（像素） | 1280 |
| `height` | `size` | integer | 高度（像素） | 720 |
| `duration` | `seconds` | integer | 时长（秒） | 5, 10 |
| `fps` | - | integer | 帧率 | 30 |
| `videoMode` | `video_mode` | string | 视频模式（Wan） | "t2v", "i2v" |

---

### 3. 通用参数（Common Parameters）

这些参数在**所有模式**下都存在：

| API 参数 | 说明 | 是否必传 |
|---------|------|---------|
| `model` | 模型名称 | ✅ 是 |
| `prompt` | 提示词 | 图片必传，视频可选 |
| `imageUrl` | 参考图片 URL | ❌ 否（图生图/图生视频） |
| `projectId` | 项目 ID | ❌ 否 |
| `storyboardId` | 分镜 ID | ❌ 否 |

---

## 🔄 参数流转关系

### 流程图

```mermaid
graph LR
    A[前端传参] --> B{检测参数类型}
    
    B -->|有 resolution<br/>+ aspectRatio| C[简单模式]
    B -->|仅 width/height<br/>等模型参数| D[高级模式]
    
    C --> E[适配器转换]
    E --> F{模型类型}
    
    F -->|Sora| G[SoraAdapter]
    F -->|Veo| H[VeoAdapter]
    F -->|Flux| I[FluxAdapter]
    F -->|其他| J[对应适配器]
    
    G --> K[转换为模型参数]
    H --> K
    I --> K
    J --> K
    
    D --> L[直接传递]
    K --> M[AIHubMixProvider]
    L --> M
    
    M --> N[读取 capabilities]
    N --> O[capability_transformer]
    O --> P[调用 AIHubMix API]
```

---

## ⚠️ 当前问题

### 问题 1: 参数检测不完整

**现状**：
```python
# ai_service.py (第 177 行)
if resolution and aspect_ratio:
    # 简单模式
```

**问题**：
- 仅检测 `resolution` 和 `aspect_ratio`
- 忽略了 `quality` 参数
- 无法处理"仅传 resolution"或"仅传 aspectRatio"的情况

**建议修正**：
```python
# 方案 1: 严格检测（推荐）
if resolution and aspect_ratio:
    # 简单模式（resolution + aspectRatio 必须同时存在）
    
# 方案 2: 宽松检测
if resolution or aspect_ratio or quality:
    # 只要有任一简单模式参数即认为是简单模式
    # 缺失的参数使用默认值
```

---

### 问题 2: 高级参数未传递

**现状**：
- Schema 定义了很多高级参数（`watermark`, `seed`, `output_format` 等）
- 但这些参数可能没有正确传递到 `AIService` 或 `Provider`

**检查点**：
1. ✅ Schema 是否定义了参数？
2. ❓ API 路由是否正确接收并传递？
3. ❓ AIService 是否在 `**kwargs` 中接收？
4. ❓ AIHubMixProvider 是否正确使用？

---

### 问题 3: Capabilities 参数未验证

**现状**：
- 数据库 `capabilities` 定义了参数的合法值（如 `quality: ['low', 'medium', 'high']`）
- 但 API 层可能没有验证用户输入是否符合 capabilities 约束

**建议**：
```python
# 在 AIService 中验证参数
def validate_params_against_capabilities(model_name: str, params: dict):
    """根据 capabilities 验证参数合法性"""
    model = await get_model(model_name)
    capabilities = model.capabilities
    
    # 验证 quality
    if 'quality' in params:
        allowed = capabilities.get('quality', {}).get('values', [])
        if params['quality'] not in allowed:
            raise ValueError(f"Invalid quality: {params['quality']}, allowed: {allowed}")
    
    # 验证 size
    # 验证 n
    # ...
```

---

## 📝 建议改进方案

### 方案 1: 完善参数检测（优先级：高）

**目标**：正确区分简单模式和高级模式

**实施**：
1. 更新 `ai_service.py` 中的检测逻辑
2. 明确简单模式触发条件
3. 添加参数日志输出

```python
# 简单模式检测（推荐）
is_simple_mode = bool(kwargs.get('resolution') and kwargs.get('aspect_ratio'))

if is_simple_mode:
    logger.info("🎯 检测到简单模式：resolution=%s, aspectRatio=%s, quality=%s",
                kwargs.get('resolution'),
                kwargs.get('aspect_ratio'),
                kwargs.get('quality', 'default'))
    # 使用适配器
else:
    logger.info("🔧 使用高级模式：width=%s, height=%s, 其他参数=%s",
                kwargs.get('width'),
                kwargs.get('height'),
                {k: v for k, v in kwargs.items() if k not in ['width', 'height']})
    # 直接传递
```

---

### 方案 2: 参数验证层（优先级：中）

**目标**：确保用户输入符合 capabilities 约束

**实施**：
1. 创建 `param_validator.py`
2. 在 API 层或 Service 层调用验证
3. 返回友好的错误提示

```python
class ParamValidator:
    @staticmethod
    async def validate_image_params(model_name: str, params: dict):
        """验证图片生成参数"""
        model = await get_model_by_name(model_name)
        if not model or not model.capabilities:
            raise ValueError(f"Model {model_name} capabilities not found")
        
        caps = model.capabilities
        
        # 验证 quality
        if 'quality' in params:
            allowed = caps.get('quality', {}).get('values', [])
            if params['quality'] not in allowed:
                raise ValueError(
                    f"Invalid quality '{params['quality']}' for {model_name}. "
                    f"Allowed values: {', '.join(allowed)}"
                )
        
        # 验证 size
        # 验证 n
        # ...
        
        return True
```

---

### 方案 3: 完善 Schema 定义（优先级：低）

**目标**：在 Schema 层添加更多高级参数

**示例**：
```python
class GenerateImageRequest(BaseModel):
    # ... 现有参数 ...
    
    # 新增高级参数
    output_format: Optional[Literal["png", "jpeg", "webp"]] = Field(
        None,
        description="输出格式（高级模式）",
        alias="outputFormat"
    )
    seed: Optional[int] = Field(
        None,
        description="随机种子（高级模式）",
        ge=0,
        le=2147483647
    )
    watermark: Optional[bool] = Field(
        None,
        description="是否添加水印（Qwen/Doubao）"
    )
    # ...
```

---

## ✅ 总结

| 参数类别 | 数量 | 检测状态 | 建议 |
|---------|------|---------|------|
| 简单模式参数 | 3 | ⚠️ 部分检测（仅 2 个） | 完善检测逻辑 |
| 高级图片参数 | 12+ | ❓ 未知 | 检查传递链路 |
| 高级视频参数 | 6+ | ❓ 未知 | 检查传递链路 |
| 通用参数 | 5 | ✅ 已实现 | - |

**下一步行动**：
1. ✅ 明确简单模式参数检测条件（`resolution` AND `aspectRatio`）
2. ⚠️ 验证高级参数是否正确传递
3. ⚠️ 实现参数验证层（可选）
4. ⚠️ 补充 Schema 定义（可选）

---

**维护人**: Claude  
**最后更新**: 2026-02-13