233 lines
5.9 KiB
Markdown
233 lines
5.9 KiB
Markdown
# 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 <token>
|
||
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 <token>" \
|
||
-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/<job_id> \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|