Sign in

v56

latestSwagger 2.0Apache 2.0raw.githubusercontent.com2026-08-0616186383.8 KB
歌曲管理

获取单个歌曲详情

根据歌曲ID获取详细信息

get/songs/{id}

Path parameters

idinteger required

歌曲ID

Response

成功返回歌曲详情

added_atstring

添加时间

albumstring

专辑名称

artiststring

艺术家/歌手

bit_rateinteger

比特率（kbps）

cover_urlstring

封面图片URL

cue_source_pathstring

CUE 来源路径（非空表示 CUE 拆分歌曲）

cue_track_indexinteger

CUE track 序号 (1-99)

dedup_keystring

去重 key(由插件定义,典型形态 "<platform>:<platform_id>");与 PluginEntryPath 组成 UNIQUE

durationnumber

播放时长（秒）

file_modified_atstring

文件修改时间(mtime，本地歌曲扫描时记录；未知为 nil)

file_pathstring

本地文件路径

file_sizeinteger

文件大小（字节）

fingerprintstring

音频指纹(Chromaprint)

fingerprint_durationnumber

指纹对应音频时长

formatstring

音频格式

genrestring

流派

idinteger

歌曲ID

is_liveboolean

是否为直播流

is_videoboolean

是否含真实视频轨(扫描时 ffprobe 探测,排除封面);客户端据此渲染画面/选择投屏 mime

isrcstring

ISRC(国际标准录音编码)

languagestring

语种

lyric_remote_urlstring

lyric_source=url 时的原始 URL(运行时由 LyricFetcher 拉取)

lyric_urlstring

歌词端点 URL(客户端唯一可见字段,指向 /api/v1/songs/{id}/lyric)

plugin_entry_pathstring

音源插件 entryPath(网络歌曲)

sample_rateinteger

采样率（Hz）

source_cover_urlstring

原始封面 URL(仅 JSON 输出,CoverURL 非空时保留原始值供编辑使用)

source_datastring

音源元数据 JSON(给插件 music/url 接口用,opaque)

source_urlstring

原始音源 URL(仅 JSON 输出,radio/remote 类型返回原始流地址供编辑使用)

stylestring

风格

titlestring

标题

trackstring

音轨号，可为 "3" 或 "3/12"（轨号/总数）

type'local' | 'remote' | 'radio'

歌曲类型：local/remote/radio

updated_atstring

最后更新时间

urlstring

网络地址

yearinteger

发行年份

Example response

{
  "added_at": "2024-01-01T12:00:00Z",
  "album": "十一月的萧邦",
  "artist": "周杰伦",
  "bit_rate": 320,
  "cover_url": "https://example.com/cover.jpg",
  "duration": 253.5,
  "file_path": "/music/周杰伦/夜曲.mp3",
  "file_size": 10485760,
  "format": "mp3",
  "genre": "Pop",
  "id": 1,
  "language": "国语",
  "plugin_entry_path": "my-source",
  "sample_rate": 44100,
  "style": "抒情",
  "title": "夜曲",
  "track": "3/12",
  "type": "local",
  "updated_at": "2024-01-01T12:00:00Z",
  "url": "https://example.com/song.mp3",
  "year": 2005
}