TravelContentCreator/docs/API_INTEGRATION.md

# AIGC 服务接口对接文档

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

---

## 概述

### 服务地址

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

### 通用请求结构

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

### 通用响应结构

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

---

## 引擎列表

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

---

## 1. 选题生成 `topic_generate`

### 请求示例

```json
{
  "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 | 否 | 受众对象 |

### 响应示例

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

---

## 2. 内容生成 `content_generate`

### 请求示例

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

### 响应示例

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

---

## 3. 海报生成 `poster_generate`

### 请求示例

```json
{
  "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`**：
```json
{
  "image_urls": [
    "https://oss.example.com/images/1.jpg",
    "https://oss.example.com/images/2.jpg"
  ]
}
```

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

### 响应示例

```json
{
  "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 景区对象

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

### product 产品对象

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

### style 风格对象

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

可选值：
- `gonglue` - 攻略风
- `tuijian` - 极力推荐风

### audience 受众对象

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

可选值：
- `qinzi` - 亲子向
- `zhoubianyou` - 周边游
- `gaoshe` - 高奢酒店

---

## 错误处理

### 错误响应格式

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

响应：
```json
{
  "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
```

请求：
```json
{
  "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 可公网访问
- [ ] 测试选题生成接口
- [ ] 测试内容生成接口
- [ ] 测试海报生成接口