---
title: "预览批量整理歌曲文件"
method: POST
path: "/api/v1/songs/organize/preview"
tags: ["歌曲管理"]
---

# 预览批量整理歌曲文件

`POST /api/v1/songs/organize/preview`

dry-run 预览目录整理变更，返回每项 old_path→new_path 与状态（ok/conflict/skip/error），不移动任何文件、不改数据库。target_path 为相对 music_path 的路径。CUE 歌曲 skip；目标已存在或批内撞名 conflict。music_path 由服务端自取。

## Request body

- ServicesOrganizeItem[]
  - `id` integer
  - `target_path` string

## Response `200`

预览结果

- ServicesOrganizePreviewResult[]
  - `error` string
  - `id` integer
  - `new_path` string
  - `old_path` string
  - `status` string

## Other responses

- `400` — 请求错误

## Changes

- **2026-07-09** `ab58736ed508` — 1 info
  - endpoint added
- **2026-06-26** `be19914b7eed` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/songloft-org/apis/songloft-api/changes/api/v1/songs/organize/preview/post.md)

---

[API](https://skmtc.dev/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.dev/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc.dev/songloft-org/apis/songloft-api/revisions/7cbe0940a38b?raw)