jinye_huang/TravelContentCreator
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
TravelContentCreator/docs/AIGC_API_GUIDE.md
jinye_huang 78d54a2535 docs: 完善 API 指南，新增架构清理文档 
- AIGC_API_GUIDE.md: 添加 Prompt/参考文献/热点/配置 API
- ARCHITECTURE_CLEANUP.md: 项目架构分析，模块状态，清理计划
2025-12-10 16:35:39 +08:00

16 KiB
Raw Blame History

AIGC 服务 API 指南

更新时间: 2024-12-10

概述

AIGC 服务提供三个核心功能：

  1. 选题生成 (topic_generate) - 生成营销选题
  2. 内容生成 (content_generate) - 生成小红书风格文案
  3. 海报生成 (poster_smart_v2) - AI 文案 + 预览图 + Fabric JSON

统一调用入口

POST /api/v2/aigc/execute

请求格式

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

响应格式

{
  "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 结构

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

请求示例

{
  "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": "亲子家庭"}
  }
}

返回数据

{
  "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 保留框架，换主体改写

请求示例

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

返回数据

{
  "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 拿铁棕

请求示例

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

返回数据

{
  "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

// 加载到 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, ...}      │
└─────────────────────────────────────────────────────────────┘

运行服务

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

查看可用引擎

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

测试脚本

# 测试选题生成
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 示例

POST /api/v1/prompt/render

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

返回

{
  "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 重载缓存

获取标题示例

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

返回

{
  "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 添加自定义热点

获取百度热搜

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

返回

{
  "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 风格+人群

获取所有配置

GET /api/v2/aigc/config/all

返回

{
  "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 引擎，无数据库依赖