# Jellyfin API 搜索电影

> 服务器地址和 API Key 见 `jellyfin-config.md`

## API 端点

```
GET /Items
```

## 搜索参数

| 参数 | 说明 |
|------|------|
| `searchTerm` | 搜索关键词 |
| `userId` | 用户ID |
| `limit` | 返回结果数量限制（默认 100） |
| `startIndex` | 起始索引 |
| `recursive` | 是否递归搜索（默认 true） |
| `includeItemTypes` | 项目类型（如 "Movie", "Series", "Episode"） |
| `sortOrder` | 排序方式（"Ascending", "Descending"） |
| `fields` | 返回额外字段 |
| `minYear` / `maxYear` | 按年份筛选 |

## 请求示例

### 基础搜索
```
GET {ServerUrl}/Items?searchTerm=电影名&includeItemTypes=Movie
X-Emby-Authorization: MediaBrowser Client="OpenClaw", Device="PC", DeviceId="openclaw", Version="1.0", Token="{ApiKey}"
```

### 分页搜索
```
GET {ServerUrl}/Items?searchTerm=动作&includeItemTypes=Movie&limit=20&startIndex=0&sortOrder=Descending
X-Emby-Authorization: MediaBrowser Client="OpenClaw", Device="PC", DeviceId="openclaw", Version="1.0", Token="{ApiKey}"
```

### 按年份筛选
```
GET {ServerUrl}/Items?searchTerm=2024&includeItemTypes=Movie&minYear=2024
X-Emby-Authorization: MediaBrowser Client="OpenClaw", Device="PC", DeviceId="openclaw", Version="1.0", Token="{ApiKey}"
```

## Python 示例

```python
import requests

# 从 jellyfin-config.md 读取配置
SERVER_URL = "http://127.0.0.1:8096"
API_KEY = "8cbcfe4d7d294c8aa00412ccc853459f"

headers = {
    "X-Emby-Authorization": f'MediaBrowser Client="OpenClaw", Device="PC", DeviceId="openclaw", Version="1.0", Token="{API_KEY}"'
}

# 搜索电影
response = requests.get(
    f"{SERVER_URL}/Items",
    params={
        "searchTerm": "电影名",
        "includeItemTypes": "Movie",
        "limit": 20,
        "startIndex": 0
    },
    headers=headers
)

if response.status_code == 200:
    results = response.json()
    for item in results.get("Items", []):
        print(f"标题: {item.get('Name')}")
        print(f"年份: {item.get('ProductionYear')}")
        print(f"评分: {item.get('CommunityRating')}")
        print("-" * 50)
else:
    print(f"错误: {response.status_code}")
```

## 返回字段示例

```json
{
  "Items": [
    {
      "Name": "电影标题",
      "Id": "项目ID",
      "Type": "Movie",
      "ProductionYear": 2024,
      "CommunityRating": 8.5,
      "Overview": "剧情简介",
      "RunTimeTicks": 1234567890,
      "Genres": ["动作", "剧情"],
      "MediaSources": [...]
    }
  ],
  "TotalRecordCount": 100
}
```

## 其他端点

- `GET /Users/Me/Items` — 当前用户所有内容

## 相关文档

- 配置: `jellyfin-config.md`
- 重复电影检测: `jellyfin-dedup-howto.md`