# 搜索

按文件名、元数据、转写和审阅评论找文件，或者直接描述画面内容。结果能直接指到视频里的那一秒。

```sh
curl -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  "https://side.example.com/v1/search?q=dock+at+dusk&type=video"
```

每个词都要在文件名、附加信息（标签、提示词、转写、媒体信息、备注）或审阅评论里命中。令牌访问不到的空间不会出现在结果里。

| 参数 | 含义 |
|---|---|
| `q` | 要找的词，或者一句描述（配合 `mode=meaning`） |
| `space` | 只搜这个空间 |
| `type` | `video`、`image`、`audio`、`folder` 或 `other` |
| `mode` | `auto`（默认，先字面后意思）、`keyword` 或 `meaning` |
| `limit` | 返回多少条 |

## 结果和时间点

```json
{
  "items": [
    {
      "node": { "id": "nod_…", "name": "A001_C003.mov", "mime": "video/quicktime", "head_version_id": "ver_…" },
      "space_name": "Film A",
      "folder": "Ep01/Shots",
      "matched": ["transcript"],
      "moments": [
        { "at_ms": 12400, "until_ms": 15100, "text": "We shot the dock right at dusk.", "source": "transcript" }
      ]
    }
  ]
}
```

命中转写、带时间的审阅评论，或者（按意思搜索时）意思相近的一段转写时，结果带 **moments**：说明在媒体的哪个位置，`source` 是 `transcript`、`comments` 或 `meaning`。可以让用户直接跳过去：网页版的文件页接受 `?t=<毫秒>`，分享页接受 `#t=<秒>`。

## 按意思搜索

服务器配了向量模型时，字面结果之后会补上意思相近的文件，标为 `"matched": ["meaning"]` 并带 `score`。所以可以直接描述想找的内容，而不用猜文件名：

```sh
sidespace search "两个人在海边吵架" --space "Film A"
#   Film A: Ep03/IMG_0042.mov  [meaning 0.62]
#         0:40.0  Look at the waves crashing on the shore.  (meaning)
```

服务器没配模型时 `mode=meaning` 返回 `400`。MCP 的 `search` 工具和两个 SDK 都支持同样的 `mode`，并原样返回 `moments` 和 `score`。

```ts tab=TypeScript
const hits = await side.search("两个人在海边吵架", { space: "Film A", mode: "meaning" });
```

```python tab=Python
hits = side.search("两个人在海边吵架", space="Film A", mode="meaning")
```