---
title: "批量添加网络歌曲"
method: POST
path: "/songs/remote"
tags: ["歌曲管理"]
---

# 批量添加网络歌曲

`POST /songs/remote`

批量添加网络歌曲到数据库。cover_url 支持以 "/" 开头的相对路径（插件场景下由服务端自动解析为内部 URL，与歌词 lyric_remote_url 的解析机制一致）。lyric_remote_url 为歌词远程 URL 直传字段，提供时优先于 lyric + lyric_source=url 的间接方式。副作用：插入成功后，对缺失技术元数据（duration/bitrate/samplerate/format）的歌曲异步探测补齐（限并发后台执行，不阻塞响应），确保 WebDAV 等无法自带时长的音源在首次播放前就落库 duration，供音箱等仅依赖服务端时长的消费端自动切歌。

## Request body

- object[]
  - `album` string
  - `artist` string
  - `cover_url` string
  - `dedup_key` string
  - `duration` number
  - `is_video` boolean
  - `lyric` string
  - `lyric_remote_url` string
  - `lyric_source` string
  - `plugin_entry_path` string
  - `source_data` string
  - `title` string
  - `url` string

## Response `201`

添加成功

- object
  - `count` integer
  - `songs` ModelsSong[]
    - `added_at` string — 添加时间
    - `album` string — 专辑名称
    - `artist` string — 艺术家/歌手
    - `bit_rate` integer — 比特率（kbps）
    - `cover_url` string — 封面图片URL
    - `cue_source_path` string — CUE 来源路径（非空表示 CUE 拆分歌曲）
    - `cue_track_index` integer — CUE track 序号 (1-99)
    - `dedup_key` string — 去重 key(由插件定义,典型形态 "<platform>:<platform_id>");与 PluginEntryPath 组成 UNIQUE
    - `duration` number — 播放时长（秒）
    - `file_modified_at` string — 文件修改时间(mtime，本地歌曲扫描时记录；未知为 nil)
    - `file_path` string — 本地文件路径
    - `file_size` integer — 文件大小（字节）
    - `fingerprint` string — 音频指纹(Chromaprint)
    - `fingerprint_duration` number — 指纹对应音频时长
    - `format` string — 音频格式
    - `genre` string — 流派
    - `id` integer — 歌曲ID
    - `is_live` boolean — 是否为直播流
    - `is_video` boolean — 是否含真实视频轨(扫描时 ffprobe 探测,排除封面);客户端据此渲染画面/选择投屏 mime
    - `isrc` string — ISRC(国际标准录音编码)
    - `language` string — 语种
    - `lyric_remote_url` string — lyric_source=url 时的原始 URL(运行时由 LyricFetcher 拉取)
    - `lyric_url` string — 歌词端点 URL(客户端唯一可见字段,指向 /api/v1/songs/{id}/lyric)
    - `plugin_entry_path` string — 音源插件 entryPath(网络歌曲)
    - `sample_rate` integer — 采样率（Hz）
    - `source_cover_url` string — 原始封面 URL(仅 JSON 输出,CoverURL 非空时保留原始值供编辑使用)
    - `source_data` string — 音源元数据 JSON(给插件 music/url 接口用,opaque)
    - `source_url` string — 原始音源 URL(仅 JSON 输出,radio/remote 类型返回原始流地址供编辑使用)
    - `style` string — 风格
    - `title` string — 标题
    - `track` string — 音轨号，可为 "3" 或 "3/12"（轨号/总数）
    - `type` 'local' | 'remote' | 'radio' — 歌曲类型：local/remote/radio
    - `updated_at` string — 最后更新时间
    - `url` string — 网络地址
    - `year` integer — 发行年份

## Other responses

- `400` — 请求数据错误
- `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)