---
title: "全量更新歌曲参与歌手"
method: PUT
path: "/songs/{id}/artists"
tags: ["歌曲管理"]
---

# 全量更新歌曲参与歌手

`PUT /songs/{id}/artists`

用请求体整组替换一首歌的参与歌手（删旧建新）。请求体 artists 数组每一项含 name/role/position：role 取 artist（主唱/表演者）或 album_artist（专辑歌手），缺省 artist；position 为同角色内展示顺序（可省略）。主要解决对唱/合唱歌曲只存了一个歌手、按搭档检索不到的问题——可在此手动补录搭档。同时按 role=artist 的名字重建 songs.artist 显示串（对唱得到 "A & B"）。角色非法返回 400；歌曲不存在返回 404。

## Path parameters

- `id` integer, required

## Request body

- HandlersSongArtistsRequest
  - `artists` ModelsArtistInput[]
    - `name` string
    - `position` integer
    - `role` string — artist | album_artist，缺省 artist

## Response `200`

更新后的参与歌手列表

- HandlersSongArtistsResponse
  - `artists` ModelsSongArtist[]
    - `artist` ModelsArtist
      - `created_at` string
      - `id` integer
      - `name` string
    - `position` integer — 同角色内的展示顺序
    - `role` string — artist | album_artist

## Other responses

- `400` — 无效的歌曲 ID 或角色非法
- `404` — 歌曲不存在

## Changes

- **2026-09-14** `8e117ed63d1a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/songloft-org/apis/songloft-api/changes/songs/:id/artists/put.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/03abcc98ecdf?raw)