media/API文档.md

# Marlin-2B Video VLM API 文档

## 基础信息
- 服务地址：`http://0.0.0.0:8900`
- 模型：Marlin-2B
- 设备：Apple Silicon (MPS) / CUDA / CPU

---

## 1. 健康检查接口

**接口路径**：`GET /health`

**请求示例**：
```bash
curl http://localhost:8900/health
```

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

**返回示例**：
```json
{
  "status": "ok",
  "model": "Marlin-2B",
  "device": "mps"
}
```

---

## 2. 视频字幕生成接口

**接口路径**：`POST /caption`

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

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

**请求示例**：
```bash
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 | 事件描述 |

**返回示例**：
```json
{
  "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 | 字符串 | 是 | 自然语言事件查询，例如 "一个人进入房间" |

**请求示例**：
```bash
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 | 输出格式是否符合训练格式 |

**返回示例**：
```json
{
  "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 |

**请求示例**：
```bash
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 | 生成的文本内容 |

**返回示例**：
```json
{
  "text": "这个视频展示了..."
}
```

---

## 错误响应

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

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

**错误响应示例**：
```json
{
  "detail": "Caption failed: 错误详情"
}
```