API 接口文档

本文档提供了 Image Maker 系统的 RESTful API 说明，帮助开发者快速对接图片生成、AI 排版等核心能力。

认证鉴权 (Authentication)

所有带有 🔒 需鉴权 标记的 API 接口，均需要在请求头中携带正确的授权 Token。

# 请求头格式
Authorization: Bearer <你的_VIP_TOKEN>
GET (获取)

/api/templates

🔒 需鉴权

获取系统中所有可用的预制模板列表。

请求示例 (cURL)

curl --request GET \
  --url 'http://127.0.0.1:8000/api/templates'

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/generate/from-template/xiaohongshu_cover_4' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "生成 国庆宣传 产品是 银耳"
  }'

响应示例 (成功)

[
  {
    "id": "template_id_1",
    "name": "极简名片",
    "variables": {
      "title": "主标题",
      "avatar": "头像URL"
    },
    "width": 800,
    "height": 600
  }
]
POST (提交)

/api/render/{template_id}

🔒 需鉴权

根据指定的模板 ID，手动传入变量参数渲染生成图片。

请求参数 (Content-Type: application/json)

字段 类型 必填 说明
variables 对象 (Object) 是 模板所需的变量键值对
format 字符串 (String) 否 "auto" (默认,含动画则出GIF) 或 "jpg" 或 "gif" 或 "webp"
width 整数 (Integer) 否 覆盖模板默认宽度
height 整数 (Integer) 否 覆盖模板默认高度
style 字符串 (String) 否 排版风格选择，如 "bold"、"card" 等，不传则由 AI 自动选择或使用模板默认值
theme 字符串 (String) 否 主题色选择，如 "sunset"、"ocean" 等，不传则由 AI 自动选择或使用模板默认值

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/render/xiaohongshu_cover_4' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "variables": {
      "title": "测试标题",
      "subtitle": "测试副标题"
    },
    "format": "auto"
  }'

响应示例 (成功)

{
  "success": true,
  "message": "图片生成成功",
  "url": "/api/outputs/xxx.jpg",
  "image_url": "http://127.0.0.1:8000/api/outputs/xxx.jpg"
}
POST (提交)

/api/generate/from-template/{template_id}

🔒 需鉴权

模式一：通过大模型理解用户的一段自然语言提示词，自动提取并填入指定模板的参数，并生成图片。

新增功能：混合模式（部分参数由 AI 生成，部分参数由您指定）

通过传入 specified_variables 参数，您可以指定某些参数的值（如背景图、标题等），AI 将只生成剩余的参数。这样可以更好地控制关键元素，同时让 AI 填充其他内容。

请求参数 (Content-Type: application/json)

字段 类型 必填 说明
prompt 字符串 (String) 是 自然语言需求描述
specified_variables 对象 (Object) 否
用户指定的参数值，AI 不会覆盖这些值
例如：{"bg_img": "https://...", "title": "我的标题"}
format 字符串 (String) 否 "auto" (默认) 或 "jpg"
width 整数 (Integer) 否 覆盖模板默认宽度
height 整数 (Integer) 否 覆盖模板默认高度
style 字符串 (String) 否 排版风格选择，如 "bold"、"card" 等，不传则 AI 自动选择
theme 字符串 (String) 否 主题色选择，如 "sunset"、"ocean" 等，不传则 AI 自动选择

使用场景示例

场景 1：指定背景图和标题，让 AI 生成内容
{
  "prompt": "关于读书的感悟，强调独立思考的重要性",
  "specified_variables": {
    "bg_img": "https://picsum.photos/1080/1440?random=5",
    "title_line1": "读书不是为了",
    "title_line2": "成为别人的样子"
  }
}
场景 2：完全让 AI 生成（不传 specified_variables）
{
  "prompt": "关于孤独的思考，中年人的感悟"
}

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/generate/from-template/read_content_1' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "关于读书的感悟，强调独立思考",
    "specified_variables": {
      "bg_img": "https://picsum.photos/1080/1440?random=5",
      "title_line1": "读书不是为了",
      "title_line2": "成为别人的样子"
    },
    "format": "auto"
  }'

响应示例 (成功)

{
  "success": true,
  "message": "AI 辅助模板生成成功",
  "url": "/api/outputs/xxx.jpg",
  "image_url": "http://127.0.0.1:8000/api/outputs/xxx.jpg",
  "variables": {
    "bg_img": "https://picsum.photos/1080/1440?random=5",
    "title_line1": "读书不是为了",
    "title_line2": "成为别人的样子",
    "content": "AI 自动生成的内容..."
  }
}
POST (提交)

/api/generate/from-scratch

🔒 需鉴权

模式二：大模型根据用户需求直接从零生成画布排版配置并出图。支持多轮迭代修改。

请求参数 (Content-Type: application/json)

字段 类型 必填 说明
prompt 字符串 (String) 是 详细的排版与设计需求
previous_template_id 字符串 (String) 否 传入历史生成的临时模板ID，AI 将在其基础上进行修改
width / height 整数 (Integer) 否 强制指定画布尺寸

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/generate/from-scratch' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "生成一个科技感的海报，背景是深蓝色",
    "width": 800,
    "height": 1200
  }'

响应示例 (成功)

{
  "success": true,
  "message": "AI 从零生成模板成功",
  "url": "/api/outputs/xxx.jpg",
  "image_url": "http://127.0.0.1:8000/api/outputs/xxx.jpg",
  "template_id": "temp_ai_xxxx",
  "template": { ...画布配置JSON... }
}
POST (提交)

/api/generate/random-idea

🔒 需鉴权

通过 AI 生成符合社交平台（如小红书）审美的高质量随机卡片设计提示词，可直接用于从零生成接口。

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/generate/random-idea' \
  --header 'Authorization: Bearer YOUR_TOKEN'

响应示例 (成功)

POST (提交)

/api/video/to-animated

🔒 需鉴权

将视频按指定时间段切分，转换为 WebP 或 GIF 动态图。支持指定转换数量或自动切分整个视频。

分段逻辑说明
  • 指定数量：如 count=1, segment_duration=3，则只转换视频前 3 秒为 1 张动图
  • 未指定数量：按 segment_duration 切分整个视频，每段生成一张动图
  • 尾部丢弃：如果剩余视频不足 segment_duration 秒，则丢弃该段

请求参数 (Content-Type: application/json)

字段 类型 必填 说明
video_url 字符串 (String) 是 视频 URL 或本地文件路径
segment_duration 整数 (Integer) 否 每段视频的秒数，默认 3
count 整数 / null 否 生成动图数量；null（默认）则切分整个视频
fps 整数 (Integer) 否 抽帧帧率，默认 10
max_width 整数 (Integer) 否 输出最大宽度（超出自动缩放），默认 720
format 字符串 (String) 否 输出格式 "webp"（默认）或 "gif"
quality 整数 (Integer) 否 WebP 质量（0-100），默认 75

使用场景示例

场景 1：只转换视频前 3 秒为 1 张动图
{
  "video_url": "https://example.com/video.mp4",
  "segment_duration": 3,
  "count": 1
}
场景 2：将整个视频按 5 秒一段全部转换（尾部不足 5 秒丢弃）
{
  "video_url": "https://example.com/video.mp4",
  "segment_duration": 5,
  "format": "gif"
}

请求示例 (cURL)

curl --request POST \
  --url 'http://127.0.0.1:8000/api/video/to-animated' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://example.com/video.mp4",
    "segment_duration": 3,
    "count": 1,
    "fps": 10,
    "max_width": 720,
    "format": "webp",
    "quality": 75
  }'

响应示例 (成功)

{
  "success": true,
  "message": "视频转动态图成功",
  "images": [
    {
      "url": "/api/outputs/video_segment_0.webp",
      "image_url": "http://127.0.0.1:8000/api/outputs/video_segment_0.webp"
    }
  ]
}