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": "这个视频展示了..."
}

---

错误响应

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

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

错误响应示例：

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