From cf7af5cfa58666a6fd0629eacd65517913a50765 Mon Sep 17 00:00:00 2001 From: zerosaturation Date: Tue, 7 Apr 2026 23:35:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20MiniMax=20?= =?UTF-8?q?=E5=9B=BE=E7=94=9F=E5=9B=BE=20API=20=E5=BC=82=E6=AD=A5=E9=9B=86?= =?UTF-8?q?=E6=88=90=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- ...6-04-07-minimax-image-generation-design.md | 232 ++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md diff --git a/docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md b/docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md new file mode 100644 index 0000000..bf8a2f1 --- /dev/null +++ b/docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md @@ -0,0 +1,232 @@ +# MiniMax 图生图 API 集成设计方案 + +## 概述 + +前端传递参数 → 后端异步调用 MiniMax 图生图 API → 前端轮询任务状态 → 返回结果 + +## 现有架构 + +| 层级 | 技术栈 | 说明 | +|------|--------|------| +| 前端 | uni-app (Vue 3) | 使用 `uni.request` 发起请求，已有 loading 页面 | +| 后端 | Go + Gin | API Gateway 模式，Dubbo RPC 调用微服务 | +| 微服务 | Go | `assetService` 等独立服务 | +| 配置 | `.env` 文件 | API keys 等敏感配置 | + +## API 设计 + +### 1. 创建图生图任务 + +``` +POST /api/v1/assets/mints/image/generation +``` + +**请求头:** +``` +Authorization: Bearer +Content-Type: application/json +``` + +**请求体:** +```json +{ + "model": "image-01", + "prompt": "描述文本", + "aspect_ratio": "16:9", + "subject_reference": [ + { + "type": "character", + "image_file": "https://..." + } + ], + "n": 2 +} +``` + +**响应 (202 Accepted):** +```json +{ + "code": 202, + "message": "任务已创建", + "data": { + "job_id": "550e8400-e29b-41d4-a716-446655440000", + "status": "PROCESSING", + "created_at": "2026-04-07T12:00:00Z" + } +} +``` + +### 2. 查询任务状态 + +``` +GET /api/v1/assets/mints/image/generation/:job_id +``` + +**响应 (PROCESSING):** +```json +{ + "code": 200, + "message": "处理中", + "data": { + "job_id": "550e8400-e29b-41d4-a716-446655440000", + "status": "PROCESSING", + "progress": 50, + "created_at": "2026-04-07T12:00:00Z" + } +} +``` + +**响应 (COMPLETED):** +```json +{ + "code": 200, + "message": "成功", + "data": { + "job_id": "550e8400-e29b-41d4-a716-446655440000", + "status": "COMPLETED", + "progress": 100, + "images": [ + "https://api.minimaxi.com/v1/images/xxx.png" + ], + "created_at": "2026-04-07T12:00:00Z", + "completed_at": "2026-04-07T12:01:30Z" + } +} +``` + +**响应 (FAILED):** +```json +{ + "code": 200, + "message": "失败", + "data": { + "job_id": "550e8400-e29b-41d4-a716-446655440000", + "status": "FAILED", + "progress": 0, + "error_msg": "MiniMax API 调用失败: timeout", + "created_at": "2026-04-07T12:00:00Z" + } +} +``` + +## 数据模型 + +### Job 状态 (内存存储) + +```go +// ImageGenerationJob 图生图任务 +type ImageGenerationJob struct { + JobID string `json:"job_id"` + UserID int64 `json:"user_id"` + StarID int64 `json:"star_id"` + Status string `json:"status"` // PENDING, PROCESSING, COMPLETED, FAILED + Progress int `json:"progress"` // 0-100 + Images []string `json:"images,omitempty"` + ErrorMsg string `json:"error_msg,omitempty"` + Request *ImageGenerationRequest `json:"request,omitempty"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} +``` + +### DTO + +```go +// ImageGenerationRequest MiniMax 图生图请求 +type ImageGenerationRequest struct { + Model string `json:"model" binding:"required"` + Prompt string `json:"prompt" binding:"required"` + AspectRatio string `json:"aspect_ratio"` + SubjectReference []SubjectReference `json:"subject_reference"` + N int `json:"n"` +} + +type SubjectReference struct { + Type string `json:"type"` + ImageFile string `json:"image_file"` +} + +// ImageJobResponse 图生图任务响应 +type ImageJobResponse struct { + JobID string `json:"job_id"` + Status string `json:"status"` + Progress int `json:"progress"` + Images []string `json:"images,omitempty"` + ErrorMsg string `json:"error_msg,omitempty"` + CreatedAt int64 `json:"created_at"` + UpdatedAt int64 `json:"updated_at"` +} +``` + +## 后端实现 + +### 文件结构 + +``` +backend/ +├── services/assetService/ +│ └── service/ +│ └── minimax_service.go # MiniMax API 转发服务 +└── gateway/ + ├── controller/ + │ └── asset_controller.go # 新增 ImageGeneration, GetImageJob + ├── dto/ + │ └── image_dto.go # 请求/响应 DTO + └── router/ + └── router.go # 注册路由 +``` + +### 核心逻辑 + +1. **创建任务**: 生成 job_id，存储任务到内存，返回 202 +2. **异步处理**: goroutine 调用 MiniMax API，图片压缩，更新 job 状态 +3. **查询状态**: 从内存读取 job 状态返回 + +### 前端改动 + +**generation-loading.vue**: +- 调用 `POST /generation` 获取 job_id +- 轮询 `GET /generation/:job_id` 直到 `status === 'COMPLETED'` 或 `'FAILED'` +- 进度可通过 `progress` 字段模拟更新 + +## 错误处理 + +| 场景 | 处理方式 | +|------|----------| +| MiniMax API 超时 | 标记 job 为 FAILED，error_msg 包含原因 | +| 图片压缩失败 | 使用原图，继续处理 | +| Job 不存在 | 返回 404 | +| 无权访问 job | 返回 403 | + +## 文件修改清单 + +| 操作 | 文件路径 | 说明 | +|------|----------|------| +| 新增 | `backend/gateway/dto/image_dto.go` | 请求/响应 DTO | +| 新增 | `backend/services/assetService/service/minimax_service.go` | MiniMax API 转发 + 图片压缩 + 任务管理 | +| 修改 | `backend/gateway/controller/asset_controller.go` | 新增 ImageGeneration, GetImageJob | +| 修改 | `backend/gateway/router/router.go` | 注册路由 | +| 修改 | `frontend/pages/discover/generation-loading.vue` | 改为轮询模式 | + +## 依赖 + +```bash +cd backend/services/assetService && go get github.com/nfnt/resize +``` + +## 验证方案 + +1. 启动后端服务 +2. 获取 JWT token +3. 测试创建任务: + ```bash + curl -X POST http://localhost:8080/api/v1/assets/mints/image/generation \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"model":"image-01","prompt":"test","aspect_ratio":"16:9","n":1,"subject_reference":[]}' + ``` +4. 使用返回的 job_id 轮询状态: + ```bash + curl http://localhost:8080/api/v1/assets/mints/image/generation/ \ + -H "Authorization: Bearer " + ```