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": 1744118400000
  }
}

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": 1744118400000
  }
}

响应 (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": 1744118400000,
    "completed_at": 1744118490000
  }
}

响应 (FAILED):

{
  "code": 200,
  "message": "失败",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "FAILED",
    "progress": 0,
    "error_msg": "MiniMax API 调用失败: timeout",
    "created_at": 1744118400000
  }
}

数据模型

Job 状态 (内存存储)

// JobStatus 任务状态枚举
type JobStatus string

const (
    StatusPending    JobStatus = "PENDING"
    StatusProcessing JobStatus = "PROCESSING"
    StatusCompleted  JobStatus = "COMPLETED"
    StatusFailed     JobStatus = "FAILED"
)

// ImageGenerationJob 图生图任务
type ImageGenerationJob struct {
    JobID       string            `json:"job_id"`
    UserID      int64             `json:"user_id"`
    StarID      int64             `json:"star_id"`
    Status      JobStatus         `json:"status"`
    Progress    int               `json:"progress"` // 0-100
    Images      []string          `json:"images,omitempty"`
    ErrorMsg    string            `json:"error_msg,omitempty"`
    Request     *ImageGenerationRequest `json:"request,omitempty"`
    CreatedAt   int64             `json:"created_at"`  //毫秒时间戳
    UpdatedAt   int64             `json:"updated_at"`
    CompletedAt int64             `json:"completed_at,omitempty"` // 毫秒时间戳
}

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"` // 1-4
}

type SubjectReference struct {
    Type      string `json:"type"`
    ImageFile string `json:"image_file"` // 必须为有效 URL，需 SSRF 校验
}

// 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"`
    CompletedAt int64    `json:"completed_at,omitempty"`
}

后端实现

文件结构

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，存储任务到内存 map，返回 202
2. 异步处理: goroutine 调用 MiniMax API，图片压缩(最大边1024px)，更新 job 状态
3. 查询状态: 从内存读取 job 状态返回
4. 任务清理: 后台 goroutine 定期清理超期(>24h)的已完成任务

图片压缩

• 最大边压缩至 1024px，保持宽高比
• 格式转换: PNG/GIF → JPEG(质量85%)
• 返回 base64 data URI 格式

SSRF 防护

subject_reference[].image_file 必须是有效 URL，下载前需校验:

• 不能是私有 IP (10.x, 172.16-31.x, 192.168.x)
• 不能是 localhost
• 不能是内网域名
• 校验失败则拒绝请求 (400)

前端改动

generation-loading.vue:

• 调用 POST /generation 获取 job_id
• 每 3 秒轮询 GET /generation/:job_id
• 超时时间: 120 秒后显示"生成超时，请重试"
• 完成后跳转到结果页

HTTP 状态码

场景	HTTP 状态码
成功 (创建/查询)	200 / 202
参数校验失败	400
未认证	401
无权访问 job	403
Job 不存在	404
MiniMax API 失败	500

错误处理

场景	处理方式
MiniMax API 超时	标记 job 为 FAILED，error_msg 包含原因
图片压缩失败	使用原图，继续处理
SSRF 校验失败	返回 400，"无效的图片URL"
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>"