docs: 添加 MiniMax 图生图 API 异步集成设计文档
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
zerosaturation
parent
867fe27a43
commit
cf7af5cfa5
@ -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 <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>"
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user