topfans/docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md

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

请求体:

{
  "model": "image-01",
  "prompt": "描述文本",
  "aspect_ratio": "16:9",
  "subject_reference": [
    {
      "type": "character",
      "image_file": "https://..."
    }
  ],
  "n": 2
}

响应 (202 Accepted):

{
  "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):

{
  "code": 200,
  "message": "处理中",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "progress": 50,
    "created_at": "2026-04-07T12:00:00Z"
  }
}

响应 (COMPLETED):

{
  "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):

{
  "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 状态 (内存存储)

// 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

// 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	改为轮询模式

依赖

cd backend/services/assetService && go get github.com/nfnt/resize

验证方案

1. 启动后端服务
2. 获取 JWT token
3. 测试创建任务:

   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 轮询状态:

   curl http://localhost:8080/api/v1/assets/mints/image/generation/<job_id> \
     -H "Authorization: Bearer <token>"