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

# 全量更新歌曲参与歌手

`PUT /songs/{id}/artists`

## Request

- Base URL: `https://localhost:58091/api/v1`
- URL: `https://localhost:58091/api/v1/songs/{id}/artists`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/songloft-org/apis/songloft-api/docs/songs/:id/artists/put.ts> (a function with typed inputs; its response is checked against the schema)

用请求体整组替换一首歌的参与歌手（删旧建新）。请求体 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

[Operation 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/5b30bc01776a?raw)