media/API文档.md

Marlin-2B Video VLM API 文档

基础信息

• 服务地址：http://0.0.0.0:8900
• 模型：Marlin-2B
• 设备：Apple Silicon (MPS) / CUDA / CPU

---

1. 健康检查接口

接口路径：GET /health

请求示例：

curl http://localhost:8900/health

返回参数：

字段名	类型	说明
status	string	状态：ok（已加载）或 loading（加载中）
model	string	模型名称，固定为 "Marlin-2B"
device	string	运行设备：mps/cuda/cpu

返回示例：

{
  "status": "ok",
  "model": "Marlin-2B",
  "device": "mps"
}

---

2. 视频字幕生成接口

接口路径：POST /caption

功能说明：为视频生成结构化字幕，包括场景描述和带时间戳的事件列表。

请求参数（multipart/form-data）：

参数名	类型	必填	说明
video	文件	是	视频文件（支持 mp4, avi, mov, webm 等格式）
max_new_tokens	int	否	最大生成 token 数，默认值 2048

请求示例：

curl -X POST http://localhost:8900/caption \
  -F "video=@/path/to/video.mp4" \
  -F "max_new_tokens=2048"

返回参数：

字段名	类型	说明
caption	string | null	完整的原始字幕文本
scene	string | null	场景描述段落
events	array | null	事件列表，每个事件包含 start/end/description

events 数组元素：

字段名	类型	说明
start	float	事件开始时间（秒）
end	float	事件结束时间（秒）
description	string	事件描述

返回示例：

{
  "caption": "Scene: ... Events: ...",
  "scene": "这是一个室内场景...",
  "events": [
    {
      "start": 0.0,
      "end": 5.0,
      "description": "一个人走进房间"
    },
    {
      "start": 5.5,
      "end": 10.0,
      "description": "这个人坐在沙发上"
    }
  ]
}

---

3. 事件时间定位接口

接口路径：POST /find

功能说明：在视频中查找指定事件发生的时间区间（时间定位）。

请求参数（multipart/form-data）：

参数名	类型	必填	说明
video	文件	是	视频文件
event	字符串	是	自然语言事件查询，例如 "一个人进入房间"

请求示例：

curl -X POST http://localhost:8900/find \
  -F "video=@/path/to/video.mp4" \
  -F "event=一个人进入房间"

返回参数：

字段名	类型	说明
raw	string | null	原始模型输出，例如 "From 14.3 to 18.2."
span	array | null	时间区间 [开始时间, 结束时间]，单位秒
format_ok	bool	输出格式是否符合训练格式

返回示例：

{
  "raw": "From 14.3 to 18.2.",
  "span": [14.3, 18.2],
  "format_ok": true
}

---

4. 自定义提示生成接口

接口路径：POST /generate

功能说明：使用自定义提示词与视频进行交互，实现更灵活的问答。

注意：此接口需要安装 torchvision 库才能正常工作。

请求参数（multipart/form-data）：

参数名	类型	必填	说明
video	文件	是	视频文件
prompt	字符串	是	自定义文本提示词
max_new_tokens	int	否	最大生成 token 数，默认值 512
do_sample	bool	否	是否启用采样，默认 false（确定性输出）
temperature	float	否	温度参数，控制随机性，默认 1.0
top_p	float	否	top-p 采样参数，默认 1.0

请求示例：

curl -X POST http://localhost:8900/generate \
  -F "video=@/path/to/video.mp4" \
  -F "prompt=描述这个视频的内容" \
  -F "max_new_tokens=512" \
  -F "temperature=0.7"

返回参数：

字段名	类型	说明
text	string	生成的文本内容

返回示例：

{
  "text": "这个视频展示了..."
}

---

5. 字幕叠加任务接口

服务地址：http://127.0.0.1:3010

5.1 创建字幕叠加任务

接口路径：POST /video/caption

功能说明：将背景视频、字幕、文字/图片元素、背景音频合成输出最终视频。异步执行，返回 taskId。

请求参数（Content-Type: application/json）：

参数名	类型	必填	说明
video_urls	string[]	是	背景视频 URL 列表，多个会自动拼接
audio_url	string	否	背景音频 URL（配音/BGM），原视频会被消音
subtitles	SubtitleSegment[]	否	字幕时间线列表
subtitle_style	SubtitleStyle	否	字幕样式配置
elements	CaptionElement[]	否	文字/图片元素列表
callback_url	string	否	任务完成回调地址

SubtitleSegment（字幕时间线片段）：

字段	类型	必填	说明
start	float	是	开始时间（秒）
end	float	是	结束时间（秒）
text	string	是	字幕文本

SubtitleStyle（字幕样式）：

字段	类型	必填	默认值	说明
fontSize	int	否	28	字号（px）
fontColor	string	否	#FFFFFF	字体颜色（十六进制）
bgColor	string	否	#000000	字幕背景色，空=透明
bgOpacity	float	否	0.6	背景透明度，0-1
x	string	否	"center"	水平位置："left"/"center"/"right" 或像素值如 "100"
y	string	否	"bottom"	垂直位置："top"/"center"/"bottom"、像素值如 "200"、或 CSS 表达式如 "calc(100% - 300px)"

CaptionElement（自定义元素）：

字段	类型	必填	默认值	说明
type	string	是	-	元素类型："text" 或 "image"
text	string	type=text时必填	-	文字内容
imageUrl	string	type=image时必填	-	图片下载 URL
x	string	否	"center"	水平位置："left"/"center"/"right" 或像素值
y	string	否	"center"	垂直位置："top"/"center"/"bottom"、像素值、或 calc()
fontSize	int	否	36	字号（px，type=text有效）
fontColor	string	否	#FFFFFF	字体颜色
bgColor	string	否	透明	背景色，如 "#FFFF00"
bgOpacity	float	否	1.0	背景透明度，0-1
width	int	否	原图尺寸	图片显示宽度（px，type=image有效）
height	int	否	原图尺寸	图片显示高度（px，type=image有效）
startTime	float	否	0	开始显示时间（秒），0=立即显示
duration	float	否	0	持续时长（秒），0=一直显示到结束
trackIndex	int	否	1	层级（类似 z-index），越大越靠前
animation	string	否	无	动画："fadeIn"/"slideUp"/"slideLeft"/"scaleIn"

请求示例：

curl --location --request POST 'http://127.0.0.1:3010/video/caption' \
--header 'Content-Type: application/json' \
--data-raw '{
  "video_urls": [
    "http://example.com/video1.mp4",
    "http://example.com/video2.mp4"
  ],
  "audio_url": "http://example.com/audio.mp3",
  "subtitles": [
    {"start": 0.0, "end": 3.0, "text": "第一段字幕"},
    {"start": 3.0, "end": 6.0, "text": "第二段字幕"}
  ],
  "subtitle_style": {
    "fontSize": 36,
    "fontColor": "#FFFF00",
    "bgColor": "#000000",
    "bgOpacity": 0.7,
    "x": "center",
    "y": "bottom"
  },
  "elements": [
    {
      "type": "text",
      "text": "标题文字",
      "x": "center",
      "y": "60",
      "fontSize": 48,
      "fontColor": "#FF0000",
      "startTime": 0,
      "duration": 0,
      "trackIndex": 5,
      "animation": "fadeIn"
    },
    {
      "type": "image",
      "imageUrl": "http://example.com/logo.png",
      "x": "right",
      "y": "top",
      "width": 100,
      "height": 100,
      "startTime": 0,
      "duration": 0,
      "trackIndex": 5
    }
  ],
  "callback_url": "https://your-server.com/callback"
}'

返回参数：

字段名	类型	说明
taskId	string	任务 ID，用于后续查询结果

返回示例：

{
  "taskId": "CAPTION_20260602123456_abc123"
}

---

5.2 查询字幕任务结果

接口路径：GET /video/caption/{taskId}

功能说明：根据 taskId 查询字幕叠加任务的状态和输出文件。

路径参数：

参数名	类型	必填	说明
taskId	string	是	创建任务时返回的 taskId

返回参数：

字段名	类型	说明
taskId	string	任务 ID
status	string	任务状态："running"（处理中）/ "completed"（完成）/ "failed"（失败）
fileUrl	string	完成时返回：输出视频下载 URL
fileSize	int64	完成时返回：输出文件大小（字节）
fileName	string	完成时返回：输出文件名
durationStr	string	完成时返回：视频时长（如 "0:45"）
errorMessage	string	失败时返回：错误信息

返回示例（完成时）：

{
  "taskId": "CAPTION_20260602123456_abc123",
  "status": "completed",
  "fileUrl": "http://127.0.0.1:3010/storage/output.mp4",
  "fileSize": 5242880,
  "fileName": "output.mp4",
  "durationStr": "0:45"
}

返回示例（处理中）：

{
  "taskId": "CAPTION_20260602123456_abc123",
  "status": "running"
}

返回示例（失败）：

{
  "taskId": "CAPTION_20260602123456_abc123",
  "status": "failed",
  "errorMessage": "视频下载失败"
}

当请求失败时，接口返回 HTTP 错误码和错误信息：

HTTP 状态码	说明
400	请求参数错误
500	服务器内部错误
503	模型尚未加载完成

错误响应示例：

{
  "detail": "Caption failed: 错误详情"
}