ai_service/接口文档.md

# AI海报生成系统 接口文档

## 概述

AI海报生成系统是一个基于FastAPI的Web服务，集成了多个AI模型和图像处理功能，能够一键生成Vue组件代码和PSD文件。

## 系统架构

```
前端 → FastAPI服务器(8000端口) → ComfyUI服务器(101.201.50.90:8188)
                ↓
           Vue代码生成 + PSD文件合成
```

## API端点

### 1. 健康检查

**GET** `/health`

**功能**: 检查服务器状态

**响应**:
```json
{
  "status": "healthy", 
  "timestamp": "2025-01-02T20:30:00"
}
```

### 2. 主要接口 - 生成海报

**POST** `/api/generate-poster`

**功能**: 一键生成完整海报（Vue代码 + PSD文件）

**请求体**:
```json
{
  "user_input": "端午节海报，传统风格，包含荷花和龙舟",
  "session_id": "可选-用于跟踪会话"
}
```

**响应**:
```json
{
  "status": "success",
  "message": "海报生成完成",
  "data": {
    "vue_code": "完整的Vue组件代码",
    "suggestions": {
      "layer5_logo_content": {
        "text": "主办方",
        "color": "#000000"
      },
      "layer6_title_content": {
        "content": "端午节安康",
        "font_name": "SimHei",
        "color": "#7E0C6E"
      },
      "layer7_subtitle_content": {
        "content": "粽叶飘香，龙舟竞渡",
        "font_name": "Microsoft YaHei",
        "color": "#000000"
      }
    },
    "analysis_result": {
      "analyzed_prompt": "端午节海报，传统风格",
      "main_theme": "端午节祝福",
      "width": 1080,
      "height": 1920,
      "keywords": ["端午节", "传统", "荷花", "龙舟"]
    },
    "psd_file_path": "生成的PSD文件路径",
    "file_size_mb": 5.93,
    "generated_images": 2,
    "files": {
      "vue_file": "Vue文件路径",
      "psd_file": "PSD文件路径"
    }
  },
  "session_id": "会话ID"
}
```

### 3. 文件下载

**GET** `/api/download/{file_type}?session_id={session_id}`

**功能**: 下载生成的文件

**参数**:
- `file_type`: 文件类型 (`vue` | `psd` | `json`)
- `session_id`: 会话ID（查询参数）

**响应**: 直接返回文件下载

### 4. 获取生成状态

**GET** `/api/status/{session_id}`

**功能**: 获取指定会话的生成状态和信息

**响应**:
```json
{
  "status": "success",
  "message": "状态获取成功",
  "data": {
    "user_input": "用户输入",
    "analysis_result": "分析结果",
    "suggestions": "文案建议", 
    "vue_path": "Vue文件路径",
    "psd_path": "PSD文件路径",
    "psd_size_mb": 5.93,
    "created_at": "2025-01-02T20:30:00"
  },
  "session_id": "会话ID"
}
```

## 内部模块接口

### 1. prompt_analysis

**函数**: `llm_user_analysis(user_input)`

**功能**: 使用DeepSeek模型分析用户输入

**参数**:
- `user_input` (str): 用户输入的海报需求

**返回值**:
```json
{
  "analyzed_prompt": "原始用户输入",
  "keywords": ["关键词1", "关键词2"],
  "width": 1080,
  "height": 1920,
  "batch_size": 2,
  "poster_type": "海报类型",
  "main_theme": "主要主题",
  "style_preference": "风格偏好",
  "color_preference": "颜色偏好"
}
```

### 2. flux_con

**函数**: `comfyui_img_info(user_input_analysis_result, system_prompt)`

**功能**: 调用ComfyUI生成图片

**参数**:
- `user_input_analysis_result`: 用户输入分析结果
- `system_prompt`: 系统提示词

**返回值**:
```json
[
  {
    "picture_name": "图片文件名",
    "picture_type": "png",
    "picture_description": "图片描述",
    "picture_size": "1080x1920"
  }
]
```

### 3. generate_text

**函数**: `get_poster_content_suggestions(analyzed_prompt)`

**功能**: 使用Kimi生成文案建议

**参数**:
- `analyzed_prompt` (str): 分析后的提示词

**返回值**:
```json
{
  "layer5_logo_content": {
    "text": "Logo文字",
    "color": "#000000"
  },
  "layer6_title_content": {
    "content": "主标题",
    "font_name": "字体名称",
    "color": "#颜色代码"
  },
  "layer7_subtitle_content": {
    "content": "副标题",
    "font_name": "字体名称", 
    "color": "#颜色代码"
  }
}
```

### 4. generate_layout

**函数**: `generate_vue_code(prompt)`

**功能**: 使用DeepSeek生成Vue组件代码

**参数**:
- `prompt` (str): 包含布局要求的提示词

**返回值**: Vue组件代码字符串

### 5. export_psd_from_json

**函数**: `create_psd_from_images(image_paths, output_path, canvas_size, mode)`

**功能**: 创建PSD文件

**参数**:
- `image_paths` (List[str]): 图片路径列表
- `output_path` (str): 输出PSD文件路径
- `canvas_size` (Tuple[int, int]): 画布大小
- `mode` (str): 颜色模式

## 错误处理

**错误响应格式**:
```json
{
  "detail": "错误描述信息"
}
```

**常见错误码**:
- `400`: 请求参数错误
- `404`: 资源不存在（会话不存在、文件不存在）
- `500`: 服务器内部错误

## 使用示例

### JavaScript调用示例

```javascript
// 生成海报
async function generatePoster(userInput) {
  const response = await fetch('http://localhost:8000/api/generate-poster', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ user_input: userInput })
  });
  
  const result = await response.json();
  
  if (result.status === 'success') {
    console.log('Vue代码:', result.data.vue_code);
    console.log('文案建议:', result.data.suggestions);
    
    // 下载文件
    downloadFile(result.session_id, 'vue');
    downloadFile(result.session_id, 'psd');
  }
}

// 下载文件
function downloadFile(sessionId, fileType) {
  const url = `http://localhost:8000/api/download/${fileType}?session_id=${sessionId}`;
  window.open(url, '_blank');
}

// 使用示例
generatePoster("春节海报，红色背景，现代风格");
```

### Python调用示例

```python
import requests

# 生成海报
def generate_poster(user_input):
    url = "http://localhost:8000/api/generate-poster"
    data = {"user_input": user_input}
    
    response = requests.post(url, json=data)
    result = response.json()
    
    if result["status"] == "success":
        print("Vue代码:", result["data"]["vue_code"])
        session_id = result["session_id"]
        
        # 下载PSD文件
        download_url = f"http://localhost:8000/api/download/psd?session_id={session_id}"
        psd_response = requests.get(download_url)
        
        with open("poster.psd", "wb") as f:
            f.write(psd_response.content)

# 使用示例
generate_poster("端午节海报，传统风格")
```

## 工作流程

1. **接收请求**: 前端发送用户输入到 `/api/generate-poster`
2. **分析输入**: 使用DeepSeek分析用户需求
3. **生成图片**: 调用ComfyUI(101.201.50.90:8188)生成图片
4. **生成文案**: 使用Kimi生成文案建议
5. **生成Vue代码**: 使用DeepSeek生成Vue组件
6. **创建PSD**: 合成PSD文件（优先使用手动模板）
7. **返回结果**: 一次性返回所有生成内容
8. **文件下载**: 前端可按需下载生成的文件

## 部署说明

### 开发环境
```bash
cd E:\砚生\ai_service\scripts
python run_pipeline.py
# 选择: 2 (API服务器模式)
```

### 生产环境
- 使用PM2管理进程
- 配置Nginx反向代理
- 设置CORS允许的域名
- 配置HTTPS