TravelContentCreator/docs/AIGC_API_GUIDE.md

# AIGC 服务 API 指南

> 更新时间: 2024-12-10

## 概述

AIGC 服务提供三个核心功能：
1. **选题生成** (`topic_generate`) - 生成营销选题
2. **内容生成** (`content_generate`) - 生成小红书风格文案
3. **海报生成** (`poster_smart_v2`) - AI 文案 + 预览图 + Fabric JSON

---

## 统一调用入口

```
POST /api/v2/aigc/execute
```

### 请求格式

```json
{
  "engine": "引擎ID",
  "params": { ... },
  "async_mode": false
}
```

### 响应格式

```json
{
  "success": true,
  "data": { ... },
  "error": null
}
```

---

## 1. 选题生成 (topic_generate)

### 功能
根据景区/产品信息 + 风格/人群 + 热点事件，生成多个营销选题。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| `num_topics` | int | 否 | 生成数量，默认 5 |
| `month` | string | 是 | 目标日期，如 "2024-12" |
| `subject` | object | 否 | 主体信息 (景区/酒店等) |
| `style` | object | 否 | 风格 {id, name} |
| `audience` | object | 否 | 受众 {id, name} |
| `hot_topics` | object | 否 | 热点 {events, festivals, trending} |

### subject 结构

```json
{
  "id": "景区ID",
  "name": "景区名称",
  "type": "scenic_spot",
  "description": "景区描述",
  "location": "广州天河",
  "products": [
    {
      "id": "产品ID",
      "name": "产品名称",
      "price": "199元",
      "description": "产品描述"
    }
  ]
}
```

### 请求示例

```json
{
  "engine": "topic_generate",
  "params": {
    "num_topics": 5,
    "month": "2024-12",
    "subject": {
      "id": "123",
      "name": "长隆野生动物世界",
      "description": "亚洲最大的野生动物主题公园",
      "location": "广州番禺",
      "products": [
        {"name": "成人票", "price": "299元"}
      ]
    },
    "style": {"id": "xiaohongshu", "name": "小红书种草"},
    "audience": {"id": "family", "name": "亲子家庭"}
  }
}
```

### 返回数据

```json
{
  "success": true,
  "data": {
    "topics": [
      {
        "index": 1,
        "date": "12月15日",
        "title": "周末带娃去长隆，这份攻略请收好！",
        "subject_name": "长隆野生动物世界",
        "product_name": "成人票",
        "style": "小红书种草",
        "audience": "亲子家庭",
        "hook": "周末遛娃好去处",
        "subject_id": "123",
        "style_id": "xiaohongshu",
        "audience_id": "family"
      }
    ],
    "count": 5
  },
  "metadata": {
    "input_tokens": 1200,
    "output_tokens": 800,
    "time_cost": 3.5
  }
}
```

---

## 2. 内容生成 (content_generate)

### 功能
根据选题生成完整的小红书风格文案（标题 + 正文 + 标签）。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| `topic` | object | 是 | 选题信息 (来自 topic_generate) |
| `subject` | object | 否 | 主体信息 |
| `style` | object | 否 | 风格 |
| `audience` | object | 否 | 受众 |
| `reference` | object | 否 | 参考内容 {mode, title, content} |
| `enable_judge` | bool | 否 | 是否启用审核，默认 true |

### reference.mode 说明

| mode | 说明 |
|------|------|
| `none` | 不使用参考，使用内置范文库 |
| `reference` | 参考风格，原创内容 |
| `rewrite` | 保留框架，换主体改写 |

### 请求示例

```json
{
  "engine": "content_generate",
  "params": {
    "topic": {
      "index": 1,
      "date": "12月15日",
      "title": "周末带娃去长隆",
      "subject_name": "长隆野生动物世界",
      "style": "小红书种草",
      "audience": "亲子家庭"
    },
    "subject": {
      "name": "长隆野生动物世界",
      "description": "亚洲最大的野生动物主题公园",
      "location": "广州番禺"
    },
    "enable_judge": true
  }
}
```

### 返回数据

```json
{
  "success": true,
  "data": {
    "content": {
      "title": "广州遛娃天花板！长隆动物园超全攻略",
      "content": "姐妹们！这个周末带娃去长隆...",
      "tag": "#长隆野生动物世界 #广州亲子游 #周末遛娃"
    },
    "original_content": { ... },
    "topic": { ... },
    "judged": true,
    "judge_analysis": "标题吸引力强，正文结构清晰..."
  },
  "metadata": {
    "input_tokens": 2000,
    "output_tokens": 1200,
    "time_cost": 5.2
  }
}
```

---

## 3. 海报生成 (poster_smart_v2)

### 功能
AI 生成文案 + 渲染预览图 + 输出 Fabric.js JSON（供前端编辑）。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| `category` | string | 是 | 类型: 景点/美食/酒店/民宿/活动/攻略 |
| `name` | string | 是 | 名称 |
| `description` | string | 否 | 描述 |
| `price` | string | 否 | 价格 |
| `location` | string | 否 | 地点 |
| `features` | string | 否 | 特色/卖点，逗号分隔 |
| `image_url` | string | 否 | 背景图 URL |
| `override_layout` | string | 否 | 强制布局 |
| `override_theme` | string | 否 | 强制主题 |
| `skip_ai` | bool | 否 | 跳过 AI 生成 |

### 可用布局

| 布局 | 说明 | 适用场景 |
|-----|------|----------|
| `hero_bottom` | 底部文字，图片铺满 | 景点、攻略 |
| `overlay_center` | 文字居中叠加 | 活动、大标题 |
| `overlay_bottom` | 底部毛玻璃 | 美食探店 |
| `split_vertical` | 左图右文 | 民宿、酒店 |
| `card_float` | 悬浮卡片 | 酒店、精品推荐 |

### 可用主题

| 主题 | 色系 |
|-----|------|
| `ocean` | 海洋蓝 |
| `sunset` | 日落橙 |
| `peach` | 蜜桃粉 |
| `mint` | 薄荷绿 |
| `latte` | 拿铁棕 |

### 请求示例

```json
{
  "engine": "poster_smart_v2",
  "params": {
    "category": "景点",
    "name": "正佳极地海洋世界",
    "description": "位于广州正佳广场的大型海洋馆",
    "price": "199元/人",
    "location": "广州天河",
    "features": "企鹅馆, 海豚表演, 儿童乐园",
    "image_url": "https://example.com/ocean.jpg"
  }
}
```

### 返回数据

```json
{
  "success": true,
  "data": {
    "preview_base64": "iVBORw0KGgoAAAANSUhEUg...",
    "fabric_json": {
      "version": "5.3.0",
      "canvas": {
        "width": 1080,
        "height": 1440,
        "backgroundColor": "#E8F4F8"
      },
      "layout": "hero_bottom",
      "theme": "ocean",
      "objects": [
        {
          "id": "background_image",
          "type": "image",
          "src": "https://example.com/ocean.jpg",
          "left": 0, "top": 0,
          "width": 1080, "height": 1440
        },
        {
          "id": "title",
          "type": "textbox",
          "text": "带娃必去正佳极地海洋世界",
          "left": 48, "top": 1085,
          "fontSize": 96,
          "fontFamily": "PingFang SC"
        },
        {
          "id": "price",
          "type": "text",
          "text": "¥199",
          "left": 48, "top": 1260
        }
      ]
    },
    "layout": "hero_bottom",
    "theme": "ocean",
    "content": {
      "title": "带娃必去正佳极地海洋世界",
      "subtitle": "室内恒温海洋馆，亲子互动超轻松",
      "highlights": ["企鹅馆", "海豚表演", "儿童乐园"],
      "price": "¥199",
      "price_suffix": "/人"
    }
  }
}
```

### 前端使用 Fabric JSON

```javascript
// 加载到 Fabric.js 画布
const canvas = new fabric.Canvas('canvas');
canvas.loadFromJSON(response.data.fabric_json, () => {
  canvas.renderAll();
});

// 用户编辑后导出
const editedJson = canvas.toJSON();
const finalImage = canvas.toDataURL('image/png');
```

---

## 数据流

```
┌─────────────────────────────────────────────────────────────┐
│                      Java 端 (调用方)                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              POST /api/v2/aigc/execute                       │
│                                                             │
│  {                                                          │
│    "engine": "topic_generate" | "content_generate" |        │
│              "poster_smart_v2",                             │
│    "params": { ... }                                        │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    EngineExecutor                            │
│                                                             │
│  1. 查找引擎                                                 │
│  2. 验证参数                                                 │
│  3. 执行引擎                                                 │
│  4. 返回结果                                                 │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
┌─────────────┐    ┌─────────────────┐    ┌─────────────────┐
│topic_generate│    │content_generate │    │poster_smart_v2  │
│             │    │                 │    │                 │
│ PromptRegistry   │ PromptRegistry     │ AI + Poster_v2    │
│ + LLM       │    │ + LLM + Judge   │    │ + Fabric JSON   │
└─────────────┘    └─────────────────┘    └─────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                       返回结果                               │
│                                                             │
│  topic_generate:    {topics: [...], count: N}               │
│  content_generate:  {content: {title, content, tag}}        │
│  poster_smart_v2:   {preview_base64, fabric_json, ...}      │
└─────────────────────────────────────────────────────────────┘
```

---

## 运行服务

```bash
cd /root/TravelContentCreator
PYTHONPATH=. uvicorn api.main:app --host 0.0.0.0 --port 8001
```

## 查看可用引擎

```bash
curl http://localhost:8001/api/v2/aigc/engines
```

## 测试脚本

```bash
# 测试选题生成
python scripts/test_topic_generate.py

# 测试内容生成
python scripts/test_content_generate.py

# 测试海报生成 V2
python scripts/test_poster_smart_v2.py
```

---

## 4. 提示词管理 (Prompt)

### 功能
管理所有 Prompt 模板，支持版本控制、变量渲染。

### API 路由: `/api/v1/prompt`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/list` | 列出所有 Prompt |
| GET | `/{name}/versions` | 列出版本 |
| GET | `/{name}` | 获取 Prompt 信息 |
| GET | `/{name}/preview` | 预览原始模板 |
| POST | `/render` | 渲染 Prompt |
| POST | `/style-audience` | 获取风格/人群内容 |

### 渲染 Prompt 示例

```json
POST /api/v1/prompt/render

{
  "name": "content_generate",
  "version": "latest",
  "context": {
    "style_content": "小红书种草风",
    "demand_content": "亲子家庭",
    "object_content": "长隆野生动物世界"
  }
}
```

### 返回

```json
{
  "name": "content_generate",
  "version": "v2.1.0",
  "system_prompt": "你是一个小红书营销文案专家...",
  "user_prompt": "请为以下内容生成文案...",
  "model_params": {
    "temperature": 0.8,
    "max_tokens": 2000
  }
}
```

---

## 5. 参考文献库 (Reference)

### 功能
管理标题模板和正文范文，供内容生成引擎参考。

### API 路由: `/api/v2/reference`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/list` | 获取统计 |
| GET | `/titles` | 获取标题列表 |
| POST | `/titles` | 添加标题 |
| PUT | `/titles/{index}` | 更新标题 |
| DELETE | `/titles/{index}` | 删除标题 |
| GET | `/contents` | 获取正文列表 |
| POST | `/contents` | 添加正文 |
| POST | `/batch/add` | 批量添加 |
| POST | `/reload` | 重载缓存 |

### 获取标题示例

```bash
GET /api/v2/reference/titles?count=10&random=true
```

### 返回

```json
{
  "success": true,
  "data": {
    "titles": [
      "广州遛娃天花板！这个地方太适合带孩子了",
      "本地人私藏！XX元吃遍这条美食街"
    ],
    "count": 10
  }
}
```

---

## 6. 热点数据 (Hotspot)

### 功能
抓取百度、微博、小红书等平台热点，供选题参考。

### API 路由: `/api/v2/hotspot`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/all` | 所有来源 |
| GET | `/baidu` | 百度热搜 (实时+旅游) |
| GET | `/weibo` | 微博热搜 |
| GET | `/xiaohongshu` | 小红书热门 |
| GET | `/bing` | Bing 搜索建议 |
| GET | `/calendar` | 节日日历 |
| GET | `/travel` | 旅游相关聚合 |
| GET | `/trending` | 热门话题合并 |
| GET | `/custom` | 自定义热点 |
| POST | `/custom` | 添加自定义热点 |

### 获取百度热搜

```bash
GET /api/v2/hotspot/baidu?limit=20
```

### 返回

```json
{
  "success": true,
  "source": "baidu",
  "count": 20,
  "topics": [
    {
      "title": "冬季旅游好去处",
      "source": "baidu",
      "rank": 1,
      "heat": 4892341,
      "category": "travel",
      "url": "https://...",
      "extra": {"tab": "travel"}
    }
  ]
}
```

---

## 7. 配置查询

### API 路由: `/api/v2/aigc/config`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/config/styles` | 所有风格配置 |
| GET | `/config/audiences` | 所有人群配置 |
| GET | `/config/all` | 风格+人群 |

### 获取所有配置

```bash
GET /api/v2/aigc/config/all
```

### 返回

```json
{
  "styles": [
    {"id": "xiaohongshu", "name": "小红书种草", "description": "..."}
  ],
  "audiences": [
    {"id": "family", "name": "亲子家庭", "description": "..."}
  ]
}
```

---

## 完整 API 路由表

| 前缀 | 模块 | 说明 |
|-----|------|------|
| `/api/v2/aigc` | AIGC 引擎 | 选题/内容/海报生成 |
| `/api/v2/reference` | 参考文献 | 标题/正文管理 |
| `/api/v2/hotspot` | 热点数据 | 百度/微博/小红书 |
| `/api/v1/prompt` | 提示词 | Prompt 模板管理 |

---

## 版本历史

| 版本 | 日期 | 变更 |
|-----|------|------|
| 2.0.0 | 2024-12-10 | 新增 poster_smart_v2，双输出 |
| 2.1.0 | 2024-12-09 | content_generate 内置参考文献库 |
| 2.0.0 | 2024-12-08 | V2 引擎，无数据库依赖 |