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