---
title: "Update Speaker Roles"
method: PUT
path: "/v1/audios/{audio_id}/speakers/roles"
tags: ["Audio Emotion API"]
---

# Update Speaker Roles

`PUT /v1/audios/{audio_id}/speakers/roles`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v1/audios/{audio_id}/speakers/roles`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Set declared speaker roles (agent, customer, system, or media) by speaker_id.

``system`` and ``media`` mark known non-human audio, such as a voice
assistant or music. They are not a party. Send ``null`` to clear.

Merge-by-id: a role write does not clobber ``name``, and a rename does not
clobber ``role``. Unknown ids 422 the whole batch. Audio must be
``completed``. Owner or ``media:write``.

A re-diarising reprocess, a trim, or a transcript replace drops these
roles (#1361 writes a role-less speakers list before dispatch). Re-apply
them afterwards.

The names PUT response is still ``{speaker_id, name}`` only — if D1
refreshes local state from it, role chips vanish until reload. This
response returns the full speaker list including ``role``.

## Path parameters

- `audio_id` string, required: Unique identifier of the audio file

## Request body

- SpeakerRoleUpdate[]: List of speaker ID and role pairs. role is required; send null to clear.
  - `speaker_id` integer, required
  - `role` 'agent' | 'customer' | 'system' | 'media', nullable, required

## Response `200`

Successful Response

- SpeakerRoleUpdateResponse: Full speaker list after a role merge (id, name, role). The names PUT response stays ``List[SpeakerUpdate]`` ({speaker_id, name} only). If D1 refreshes local state from the rename response, role chips vanish until reload — re-GET or use this role PUT's response.
  - `speakers` object[], required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-01** `72330e2229c7`: 2 info
  - added the new `media` enum value to the request property `items/role/anyOf[subschema #1]/`
  - added the new `system` enum value to the request property `items/role/anyOf[subschema #1]/`
- **2026-09-08** `b10651168511`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v1/audios/:audio_id/speakers/roles/put.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)