---
title: "Set background music"
method: PUT
path: "/v1/videos/{id}/background-music"
tags: ["Videos"]
---

# Set background music

`PUT /v1/videos/{id}/background-music`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/videos/{id}/background-music`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/:id/background-music/put.ts> (a function with typed inputs; its response is checked against the schema)

Sets the video's background music track. It loops over the whole video and is included in exports. Volume is 0-1 and defaults to 0.2. Omit `sourceId` and `presetId` to change only the current track's volume or name.

## Path parameters

- `id` string, required: Unique video identifier

## Request body

- SetBackgroundMusicRequest: Set the video's background music from either your own uploaded audio (`sourceId`) or Tella's curated catalog (`presetId`), or change the current track's volume or name
  - `name` string: Optional display name for the track. Defaults to the preset's name when `presetId` is given.
  - `presetId` string: Preset ID of a curated Tella music track, from a `default` item of type `music` in `GET /v1/library`. Nothing to upload. Mutually exclusive with `sourceId`. Omit both to keep the current track and change only its `volume` or `name`.
  - `sourceId` string: Audio source ID from `POST /v1/sources` (`kind: "audio"`). Mutually exclusive with `presetId`. Omit both to keep the current track and change only its `volume` or `name`.
  - `volume` number: Track volume from 0 (silent) to 1 (full volume). Defaults to 0.2 for a new track, and to the current track's volume when neither `sourceId` nor `presetId` is given.

## Response `200`

Background music set

- object
  - `backgroundMusic` BackgroundMusic, required: One video-wide track that loops over the whole video and is included in exports
    - `durationMs` number, required: Audio track duration in milliseconds
    - `name` string, nullable, required: Optional display name for the track
    - `url` string, uri, required: HTTPS URL of the audio track
    - `volume` number, required: Track volume from 0 (silent) to 1 (full volume)

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 72 revisions in range; 1 not diffed.

- **2026-10-27** `5caf72ed8935`: 1 info
  - the `volume` request property default value `0.2` was removed
- **2026-09-28** `ac47c99c144f`: 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- **2026-09-09** `6b1132ef42fb`: 14 warning, 2 info
  - added the new `conflict` enum value to the `error` response property for the response status `400`
  - added the new `conflict` enum value to the `error` response property for the response status `401`
  - added the new `conflict` enum value to the `error` response property for the response status `403`
  - added the new `conflict` enum value to the `error` response property for the response status `404`
  - …12 more
- **2026-09-08** `7113794c5b3b`: 2 info
  - added the new optional request property `presetId`
  - the request property `sourceId` became optional

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/background-music/put.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/ca74daaf9201?raw)