API 接口

通用约定

所有接口前缀：/api
认证方式：HttpOnly Cookie（hyzc_session）
请求格式：JSON
响应格式：JSON
时间格式：ISO 8601（2026-05-01T08:32:11Z）

一、认证接口

普通用户登录

http

POST /api/auth/login
Content-Type: application/json

{
  "username": "operator01",
  "password": "********"
}

响应：

json

{
  "user": {
    "id": "usr_xxx",
    "username": "operator01",
    "role": "user"
  },
  "quotas": {
    "image": { "total": 50, "used": 0, "remaining": 50 },
    "copy":  { "total": 30, "used": 0, "remaining": 30 },
    "video": { "total": 10, "used": 0, "remaining": 10 }
  }
}

设置 Cookie：Set-Cookie: hyzc_session=...; HttpOnly; Secure; SameSite=Strict

管理员登录

http

POST /api/admin/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

首次登录

若 admin 账号不存在，使用 admin/admin123 自动创建管理员账号。

退出登录

http

POST /api/auth/logout

清除 Cookie 并标记 session 失效。

当前用户信息

http

GET /api/me

响应：

json

{
  "user": { "id": "...", "username": "...", "role": "user" },
  "quotas": { ... }
}

二、生成接口

图片生成（两段式）

Phase 1: 预扣

http

POST /api/generate/image/prepare
Content-Type: application/json

{
  "prompt": "Stainless steel kitchen rack ...",
  "model": "NanoBananaPro",
  "ratio": "1:1",
  "resolution": "1K",
  "reference_images": []
}

响应：

json

{
  "ticket": "tkt_2026-05-01_xyz",
  "provider": {
    "type": "gemini",
    "base_url": "https://generativelanguage.googleapis.com/v1beta",
    "api_key": "AIza...",
    "model": "gemini-3-pro-image-preview"
  }
}

Phase 2: 完成

http

POST /api/generate/image/complete
Content-Type: application/json

{
  "ticket": "tkt_2026-05-01_xyz",
  "status": "success"
}

必须调用 complete

若 30 秒内未调用 /complete，reaper goroutine 会自动将状态改为 failed 并回滚配额。

Listing 文案生成

http

POST /api/generate/copy
Content-Type: application/json

{
  "mode": "generate",
  "product_title": "Stainless Steel Kitchen Rack",
  "parameters": "60×30×80cm, 304 SUS, 8kg load, foldable",
  "language": "en-US",
  "graphrag_enabled": true
}

响应（流式 SSE）：

text

data: {"chunk": "Title: Foldable 3-Tier..."}
data: {"chunk": " Stainless Steel Kitchen Rack..."}
...
data: {"done": true, "tokens": 1234}

提示词智能生成

http

POST /api/generate/prompt
Content-Type: application/json

{
  "product_title": "...",
  "style": "Lifestyle Studio",
  "graphrag_enabled": true
}

响应：

json

{
  "prompt": "Generate a Lifestyle scene image...",
  "negative_prompt": "no watermark, no text overlay",
  "graphrag_subgraph": {
    "entities": [...],
    "relations": [...]
  }
}

选品分析多轮对话

http

POST /api/generate/product-analysis
Content-Type: application/json

{
  "session_id": "pa_xxx",
  "messages": [
    { "role": "user", "content": "我想做美国站厨房收纳..." },
    { "role": "assistant", "content": "..." },
    { "role": "user", "content": "基于刚才的分析..." }
  ]
}

响应（流式）：

text

data: {"chunk": "基于类目当前竞争格局..."}
data: {"chunk": "建议以下 3 条..."}
...
data: {"done": true, "extracted": {...}}

视频生成

http

POST /api/generate/video
Content-Type: application/json

{
  "prompt": "Subject: 3-tier kitchen rack...",
  "model": "veo-3.1",
  "duration": 8,
  "aspect_ratio": "16:9"
}

响应：

json

{
  "video_url": "https://cdn.veo.../xxx.mp4",
  "duration": 8,
  "tokens_used": 1
}

获取可用图片供应商

http

GET /api/generate/image/providers

响应：

json

{
  "providers": [
    {
      "type": "gemini",
      "models": ["NanoBananaPro", "NanoBanana2"],
      "ratios": ["1:1", "16:9", "9:16", ...],
      "resolutions": ["1K", "2K", "4K"]
    },
    {
      "type": "openai",
      "models": ["GPTImage2"],
      "ratios": [...]
    }
  ]
}

三、激活码接口

兑换激活码

http

POST /api/activation/redeem
Content-Type: application/json

{
  "code": "HYZC-2026-IMG50-CPY30-VID10-A8D2"
}

响应（成功）：

json

{
  "redeemed": true,
  "added_quotas": {
    "image": 50,
    "copy": 30,
    "video": 10
  },
  "current_quotas": { ... }
}

错误码：

HTTP	含义
400	激活码格式错误
404	激活码不存在
409	您已兑换过此激活码
410	激活码已过期
429	激活码使用次数已达上限

四、管理员接口（需 admin 角色）

用户管理

http

GET    /api/admin/users           # 列表（分页）
POST   /api/admin/users           # 创建
PATCH  /api/admin/users/:id       # 更新（角色、配额、状态）

创建用户示例

http

POST /api/admin/users
{
  "username": "operator01",
  "password": "auto-generated",
  "role": "user",
  "image_quota": 50,
  "copy_quota": 30,
  "video_quota": 10
}

供应商管理

http

GET    /api/admin/providers
POST   /api/admin/providers
PATCH  /api/admin/providers/:id

创建供应商示例

http

POST /api/admin/providers
{
  "name": "gemini-prod",
  "type": "gemini",
  "base_url": "https://generativelanguage.googleapis.com/v1beta",
  "api_key": "AIza...",
  "priority": 1,
  "weight": 100,
  "status": "active"
}

模型配置

http

GET   /api/admin/model-configs
PUT   /api/admin/model-configs              # 全量替换
POST  /api/admin/model-configs              # 单个 upsert

激活码管理

http

GET    /api/admin/activation-keys
POST   /api/admin/activation-keys           # 单个创建
POST   /api/admin/activation-keys/batch     # 批量创建
PATCH  /api/admin/activation-keys/:id       # 修改状态

批量创建

http

POST /api/admin/activation-keys/batch
{
  "count": 50,
  "image_quota": 50,
  "copy_quota": 30,
  "video_quota": 10,
  "max_uses": 1,
  "expires_at": "2026-12-31T23:59:59Z"
}

请求日志

http

GET /api/admin/logs?user_id=xxx&route=/api/generate/image&from=2026-05-01&to=2026-05-02&limit=100

五、错误响应格式

所有错误统一格式：

json

{
  "error": {
    "code": "QUOTA_EXHAUSTED",
    "message": "图片配额已用完",
    "details": {
      "quota_type": "image",
      "remaining": 0,
      "total": 50
    }
  }
}

常见错误码

错误码	HTTP	含义
`UNAUTHORIZED`	401	未登录或 Session 过期
`FORBIDDEN`	403	权限不足
`NOT_FOUND`	404	资源不存在
`INVALID_PARAMS`	400	参数错误
`QUOTA_EXHAUSTED`	429	配额已用完
`PROVIDER_ERROR`	502	供应商接口失败
`KEY_ALREADY_REDEEMED`	409	激活码已兑换过
`KEY_EXPIRED`	410	激活码已过期
`INTERNAL_ERROR`	500	服务器内部错误

六、CORS 与安全

CORS 策略

// 仅允许同源 + 可信 origin
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type

Rate Limiting（路线图）

未来版本将引入：

单用户单分钟 60 次 / 全局每分钟 1000 次
用 token bucket 算法 + SQLite 存储

七、API 调用示例（curl）

登录 + 图片生成完整流程

bash

# 1. 登录（保存 Cookie）
curl -c cookies.txt -X POST http://localhost:8788/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"operator01","password":"xxx"}'

# 2. 预扣
curl -b cookies.txt -X POST http://localhost:8788/api/generate/image/prepare \
  -H "Content-Type: application/json" \
  -d '{"prompt":"kitchen rack","model":"NanoBananaPro"}'

# → 返回 ticket + provider 配置

# 3. 直连 Gemini（前端通常做，curl 仅演示）
curl -X POST "${BASE_URL}/models/${MODEL}:generateContent" \
  -H "X-API-Key: ${API_KEY}" \
  -d '{...}'

# 4. 完成
curl -b cookies.txt -X POST http://localhost:8788/api/generate/image/complete \
  -H "Content-Type: application/json" \
  -d '{"ticket":"tkt_xxx","status":"success"}'

下一步

⚙️ 后端架构 —— 接口实现细节
📦 数据库设计 —— 接口背后的数据模型
🛡️ 管理后台 —— 管理接口的前端使用

API 接口 ​

一、认证接口 ​

普通用户登录 ​

管理员登录 ​

退出登录 ​

当前用户信息 ​

二、生成接口 ​

图片生成（两段式） ​

Phase 1: 预扣 ​

Phase 2: 完成 ​

Listing 文案生成 ​

提示词智能生成 ​

选品分析多轮对话 ​

视频生成 ​

获取可用图片供应商 ​

三、激活码接口 ​

兑换激活码 ​

四、管理员接口（需 admin 角色） ​

用户管理 ​

创建用户示例 ​

供应商管理 ​

创建供应商示例 ​

模型配置 ​

激活码管理 ​

批量创建 ​

请求日志 ​

五、错误响应格式 ​

常见错误码 ​

六、CORS 与安全 ​

CORS 策略 ​

Rate Limiting（路线图） ​

七、API 调用示例（curl） ​

登录 + 图片生成完整流程 ​

下一步 ​

API 接口

一、认证接口

普通用户登录

管理员登录

退出登录

当前用户信息

二、生成接口

图片生成（两段式）

Phase 1: 预扣

Phase 2: 完成

Listing 文案生成

提示词智能生成

选品分析多轮对话

视频生成

获取可用图片供应商

三、激活码接口

兑换激活码

四、管理员接口（需 admin 角色）

用户管理

创建用户示例

供应商管理

创建供应商示例

模型配置

激活码管理

批量创建

请求日志

五、错误响应格式

常见错误码

六、CORS 与安全

CORS 策略

Rate Limiting（路线图）

七、API 调用示例（curl）

登录 + 图片生成完整流程

下一步