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

# 通知歌曲播放事件

`POST /songs/{id}/played`

客户端在歌曲开始播放、播放完成或被跳过时调用此端点，后端将事件广播给已订阅播放事件的 JS 插件（通过 songloft.events.onPlayEvent 注册）。source 参数标识调用来源，如 songloft-player（官方客户端）、miot（小爱音箱插件）等。type 参数标识事件类型：play（开始播放）、finish（播放完成）、skip（用户跳过）。
副作用：当 type=play 且同时传入合法的 context_type + context_key 时，额外把该歌曲写入对应播放上下文的播放历史（见 GET /play-history），同一上下文内按歌曲去重、只保留最近 50 条。仅 type=play 会落库：finish 是同一首歌的重复信息，而 skip 上报的是上一首歌、此时上下文可能已切换，会记错归属。落库失败只记日志，不影响响应码。

## Path parameters

- `id` integer, required

## Query parameters

- `source` string
- `type` 'play' | 'finish' | 'skip'
- `context_type` 'playlist' | 'artist' | 'album' | 'genre' | 'year' | 'decade' | 'language' | 'style'
- `context_key` string

## Response `204`

无内容

## Other responses

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

---

[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/revisions/3597db751d49/schema)