---
title: "通知歌曲播放事件"
method: POST
path: "/songs/{id}/played"
tags: ["歌曲管理"]
---

# 通知歌曲播放事件

`POST /songs/{id}/played`

客户端在歌曲开始播放、播放完成或被跳过时调用此端点，后端将事件广播给已订阅播放事件的 JS 插件（通过 songloft.events.onPlayEvent 注册）。source 参数标识调用来源，如 songloft-player（官方客户端）、miot（小爱音箱插件）等。type 参数标识事件类型：play（开始播放）、finish（播放完成）、skip（用户跳过）。

## Path parameters

- `id` integer, required

## Query parameters

- `source` string
- `type` 'play' | 'finish' | 'skip'

## Response `204`

无内容

## Other responses

- `400` — 无效的歌曲 ID 或事件类型
- `404` — 歌曲不存在

---

[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)