Template

jinye_huang e0fe18966b docs: 添加 AIGC API 指南文档

整理选题、笔记、海报三个功能的:
- 调用方法和请求参数
- 数据流和返回内容
- 使用示例

2025-12-10 16:32:22 +08:00

12 KiB

Raw Blame History

AIGC 服务 API 指南

更新时间: 2024-12-10

概述

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

选题生成 (topic_generate) - 生成营销选题
内容生成 (content_generate) - 生成小红书风格文案
海报生成 (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

版本历史

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

12 KiB Raw Blame History Unescape Escape

AIGC 服务 API 指南

概述

统一调用入口

请求格式

响应格式

1. 选题生成 (topic_generate)

功能

请求参数

subject 结构

请求示例

返回数据

2. 内容生成 (content_generate)

功能

请求参数

reference.mode 说明

请求示例

返回数据

3. 海报生成 (poster_smart_v2)

功能

请求参数

可用布局

可用主题

请求示例

返回数据

前端使用 Fabric JSON

数据流

运行服务

查看可用引擎

测试脚本

版本历史

12 KiB

Raw Blame History