---
title: "Add a sound effect to a clip"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/sound-effects"
tags: ["Clips"]
---

# Add a sound effect to a clip

`POST /v1/videos/{id}/clips/{clipId}/sound-effects`

## Request

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

Adds a sound effect to a clip from Tella's curated catalog (`presetId`) or your own audio (`sourceId`).

## Path parameters

- `id` string, required: Video identifier
- `clipId` string, required: Clip identifier

## Request body

- AddClipSoundEffectRequest: Add a sound effect to a clip, from Tella's curated catalog (`presetId`) or from your own audio (`sourceId`).
  - `durationMs` integer, required
  - `name` string
  - `presetId` string: Preset ID of a curated Tella sound effect, from a `default` item in `GET /v1/library?scope=default`. Placing one copies the effect into a source owned by your workspace, so nothing needs uploading. Mutually exclusive with `sourceId`; exactly one is required.
  - `sourceId` string: Source ID for the audio, from `POST /v1/sources` (`kind: audio` with the audio's duration) or from a `private`/`workspace` item in `GET /v1/library?type=sound-effect`. When uploading, send the audio file as-is — MP3, WAV, M4A, … — no need to wrap it in an MP4. Mutually exclusive with `presetId`; exactly one is required.
  - `startTimeMs` integer, required: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
  - `volume` number: Playback volume (0 = muted, 1 = original). Defaults to 1.

## Response `200`

OK

- ClipSoundEffectResponse: A sound effect on a clip
  - `soundEffect` ClipSoundEffect, required: A sound effect on a clip.
    - `durationMs` number, required
    - `id` string, required: Sound effect ID
    - `name` string, nullable
    - `sourceId` string, nullable
    - `startTimeMs` number, required: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
    - `volume` number, required: Playback volume (1 = original).

## 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-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

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/sound-effects/post.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)