---
title: "扫描并导入本地音乐"
method: POST
path: "/scan"
tags: ["扫描管理"]
---

# 扫描并导入本地音乐

`POST /scan`

异步扫描音乐目录并导入新发现的音乐文件到数据库，立即返回，可通过进度接口查询状态。
reimport=true 时对已入库文件也重新提取元数据；默认 false 走增量（跳过已存在且时长有效的文件）。
paths 为目录级定向扫描（Issue #262）：省略/为空时扫描整个音乐根目录；非空时只扫描给定目录（含子目录），
且过期记录清理仅收敛到这些目录之内（不影响其余曲库）。每个目录必须位于音乐根目录之下，否则返回 400。

## Request body

- HandlersScanRequest
  - `paths` string[] — Paths 为目录级定向扫描（Issue #262）：为空时扫描整个音乐根目录（默认行为）； 非空时只扫描给定目录（含子目录），过期记录清理也仅收敛到这些目录之内。 每个目录必须位于音乐根目录之下，否则返回 400。
  - `reimport` boolean

## Response `200`

扫描任务已启动

- object

## Other responses

- `400` — 指定目录不在音乐目录下
- `409` — 扫描正在进行中
- `500` — 启动扫描失败

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/versions/77467de6ed1b/schema)