TravelContentCreator/docs/API_INTEGRATION.md

AIGC 服务接口对接文档

本文档供 Java 后端对接 Python AIGC 服务使用

---

概述

服务地址

POST http://aigc-service:8080/aigc/execute

通用请求结构

{
  "engine": "引擎名称",
  "params": { ... },
  "async_mode": false,
  "task_id": null,
  "callback_url": null
}

通用响应结构

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "data": { ... },
  "error": null,
  "error_code": null
}

---

引擎列表

引擎	engine 值	说明
选题生成	topic_generate	生成营销选题
内容生成	content_generate	生成小红书文案
海报生成	poster_generate	生成海报图片

---

1. 选题生成 topic_generate

请求示例

{
  "engine": "topic_generate",
  "params": {
    "num_topics": 5,
    "month": "2025-01",
    "scenic_spot": {
      "id": 1,
      "name": "天津冒险湾",
      "description": "天津最大的水上乐园...",
      "address": "天津市滨海新区...",
      "highlights": ["水上项目", "亲子设施"]
    },
    "product": {
      "id": 10,
      "name": "家庭套票",
      "price": 299,
      "original_price": 399,
      "package_info": "含2大1小门票+午餐",
      "usage_rules": "需提前1天预约"
    },
    "style": {
      "id": 1,
      "name": "攻略风",
      "prompt_key": "gonglue"
    },
    "audience": {
      "id": 1,
      "name": "亲子向",
      "prompt_key": "qinzi"
    }
  }
}

参数说明

参数	类型	必填	说明
num_topics	int	否	生成选题数量，默认 5
month	string	否	目标月份，如 "2025-01"
scenic_spot	object	是	景区完整对象
product	object	是	产品完整对象
style	object	否	风格对象
audience	object	否	受众对象

响应示例

{
  "success": true,
  "data": {
    "topics": [
      {
        "index": 1,
        "date": "2025-01-15",
        "title": "寒假遛娃好去处",
        "logic": "寒假期间亲子出游需求旺盛",
        "scenic_spot": "天津冒险湾",
        "product": "家庭套票",
        "style": "攻略风",
        "audience": "亲子向"
      }
    ],
    "count": 5
  }
}

---

2. 内容生成 content_generate

请求示例

{
  "engine": "content_generate",
  "params": {
    "topic": {
      "index": 1,
      "date": "2025-01-15",
      "title": "寒假遛娃好去处",
      "logic": "寒假期间亲子出游需求旺盛"
    },
    "scenic_spot": {
      "id": 1,
      "name": "天津冒险湾",
      "description": "天津最大的水上乐园...",
      "address": "天津市滨海新区...",
      "highlights": ["水上项目", "亲子设施"],
      "traffic_info": "地铁9号线直达"
    },
    "product": {
      "id": 10,
      "name": "家庭套票",
      "price": 299,
      "original_price": 399,
      "package_info": "含2大1小门票+午餐"
    },
    "style": {
      "id": 1,
      "name": "攻略风",
      "prompt_key": "gonglue"
    },
    "audience": {
      "id": 1,
      "name": "亲子向",
      "prompt_key": "qinzi"
    },
    "need_judge": true
  }
}

参数说明

参数	类型	必填	说明
topic	object	是	选题对象（上一步输出）
scenic_spot	object	是	景区完整对象
product	object	是	产品完整对象
style	object	否	风格对象
audience	object	否	受众对象
need_judge	bool	否	是否需要内容审核，默认 true

响应示例

{
  "success": true,
  "data": {
    "content": {
      "title": "🎢寒假遛娃｜天津冒险湾超全攻略",
      "content": "终于找到一个能让娃玩一整天的地方...",
      "tag": "#天津旅游 #亲子游 #周末去哪儿玩"
    },
    "judge_result": {
      "passed": true,
      "score": 85,
      "suggestions": []
    }
  }
}

---

3. 海报生成 poster_generate

请求示例

{
  "engine": "poster_generate",
  "params": {
    "template_id": "poster-template-1",
    "poster_content": {
      "title": "寒假特惠",
      "subtitle": "天津冒险湾家庭套票",
      "slogan": "一票畅玩全场",
      "price_text": "¥299起",
      "highlights": ["水上乐园", "亲子设施", "美食套餐"],
      "cta": "立即抢购"
    },
    "image_urls": [
      "https://oss.example.com/images/scenic1.jpg",
      "https://oss.example.com/images/scenic2.jpg"
    ],
    "scenic_spot": {
      "id": 1,
      "name": "天津冒险湾"
    },
    "product": {
      "id": 10,
      "name": "家庭套票"
    }
  }
}

参数说明

参数	类型	必填	说明
template_id	string	是	海报模板 ID
poster_content	object	否	海报文案内容
image_urls	array	推荐	图片 URL 列表
image_paths	array	备选	本地图片路径
scenic_spot	object	否	景区对象
product	object	否	产品对象

图片传输方式

推荐使用 image_urls：

{
  "image_urls": [
    "https://oss.example.com/images/1.jpg",
    "https://oss.example.com/images/2.jpg"
  ]
}

Python 端会自动下载图片并处理。

响应示例

{
  "success": true,
  "data": {
    "poster_url": "https://oss.example.com/posters/result.png",
    "poster_base64": "data:image/png;base64,...",
    "template_id": "poster-template-1"
  }
}

---

对象结构定义

scenic_spot 景区对象

{
  "id": 1,
  "name": "景区名称",
  "description": "景区描述",
  "address": "详细地址",
  "traffic_info": "交通信息",
  "highlights": ["亮点1", "亮点2"],
  "opening_hours": "营业时间",
  "tips": "游玩贴士"
}

product 产品对象

{
  "id": 10,
  "name": "产品名称",
  "price": 299,
  "original_price": 399,
  "package_info": "套餐内容",
  "usage_rules": "使用规则",
  "valid_period": "有效期",
  "stock": 100
}

style 风格对象

{
  "id": 1,
  "name": "攻略风",
  "prompt_key": "gonglue"
}

可选值：

• gonglue - 攻略风
• tuijian - 极力推荐风

audience 受众对象

{
  "id": 1,
  "name": "亲子向",
  "prompt_key": "qinzi"
}

可选值：

• qinzi - 亲子向
• zhoubianyou - 周边游
• gaoshe - 高奢酒店

---

错误处理

错误响应格式

{
  "success": false,
  "error": "错误描述",
  "error_code": "ERROR_CODE",
  "data": null
}

常见错误码

错误码	说明	处理建议
VALIDATION_ERROR	参数验证失败	检查必填参数
ENGINE_NOT_FOUND	引擎不存在	检查 engine 值
AI_RATE_LIMIT	AI 服务限流	稍后重试
AI_CONTENT_FILTER	内容被过滤	调整输入内容
NETWORK_ERROR	网络错误	检查服务连接

---

Prompt 查询接口

列出所有 Prompt

GET /prompt/v2/list

响应：

{
  "prompts": ["topic_generate", "content_generate", "content_judge", "poster_generate", "integration"],
  "count": 5
}

获取 Prompt 详情

GET /prompt/v2/{name}?version=latest

列出 Prompt 版本

GET /prompt/v2/{name}/versions

渲染 Prompt

POST /prompt/v2/render

请求：

{
  "name": "content_generate",
  "version": "latest",
  "context": {
    "style_content": "...",
    "demand_content": "...",
    "topic": { ... }
  }
}

---

迁移指南

从旧接口迁移

旧参数	新参数	说明
ppid	移除	不再使用
sid	scenic_spot.id	改为完整对象
pid	product.id	改为完整对象
images_base64	image_urls	推荐使用 URL

关键变化

1. 不再使用 ppid：Java 端需要预先解析 ppid，传递完整对象
2. 图片使用 URL：推荐传递 OSS URL，Python 端自动下载
3. 风格/受众使用 prompt_key：用于匹配 Prompt 模板

---

联调检查清单

• 确认服务地址可访问
• 确认 scenic_spot 对象包含必要字段
• 确认 product 对象包含必要字段
• 确认 style.prompt_key 值正确
• 确认 audience.prompt_key 值正确
• 确认图片 URL 可公网访问
• 测试选题生成接口
• 测试内容生成接口
• 测试海报生成接口