docs: 添加 AIGC API 指南文档
整理选题、笔记、海报三个功能的: - 调用方法和请求参数 - 数据流和返回内容 - 使用示例
This commit is contained in:
parent
2d21647f10
commit
e0fe18966b
417
docs/AIGC_API_GUIDE.md
Normal file
417
docs/AIGC_API_GUIDE.md
Normal file
@ -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 引擎，无数据库依赖 |
|
||||
Loading…
x
Reference in New Issue
Block a user