---
title: "触发批量指纹计算"
method: POST
path: "/scan/fingerprints"
tags: ["扫描管理"]
---

# 触发批量指纹计算

`POST /scan/fingerprints`

异步为本地歌曲计算音频指纹，需要 ffmpeg 支持 chromaprint。若已有任务在运行则打断重启。传入 recompute_all=true 时清空已有指纹后重新计算全部；传入 retry_failed=true 时仅重置失败项的「已尝试」标记后重试（已算好的指纹保留，适用于 ffmpeg 能力升级后恢复失败歌曲）。两者同时传入时 recompute_all 优先。

## Request body

- HandlersStartFingerprintRequest
  - `recompute_all` boolean
  - `retry_failed` boolean — RetryFailed 仅重置失败项的「已尝试」标记后重试，已算好的指纹保留。

## Response `200`

任务已启动

- object

## Other responses

- `400` — chromaprint 不可用

---

[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/ee41778dbf8f/schema)