444 lines
8.3 KiB
Markdown
444 lines
8.3 KiB
Markdown
# 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 可公网访问
|
||
- [ ] 测试选题生成接口
|
||
- [ ] 测试内容生成接口
|
||
- [ ] 测试海报生成接口
|