diff --git a/docs/AIGC_API_GUIDE.md b/docs/AIGC_API_GUIDE.md new file mode 100644 index 0000000..8665ca9 --- /dev/null +++ b/docs/AIGC_API_GUIDE.md @@ -0,0 +1,417 @@ +# 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 +``` + +--- + +## 版本历史 + +| 版本 | 日期 | 变更 | +|-----|------|------| +| 2.0.0 | 2024-12-10 | 新增 poster_smart_v2，双输出 | +| 2.1.0 | 2024-12-09 | content_generate 内置参考文献库 | +| 2.0.0 | 2024-12-08 | V2 引擎，无数据库依赖 |