---
title: "Add a Tella Motion clip"
method: POST
path: "/v1/motion/clips"
tags: ["Tella Motion"]
---

# Add a Tella Motion clip

`POST /v1/motion/clips`

## Request

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

Adds a clip at the end of a video that plays a blank Tella Motion document of its own, or your document `documentId` that no video plays yet, and returns the clip and its document. With `documentId` and no `videoId`, it makes a new video for the document, as large as its canvas, and returns its `videoId` and `editUrl`. Build what it shows with `POST /v1/motion/documents/{id}/commands`. The clip routes that edit layouts, cuts, zooms, overlays or the transcript refuse a Tella Motion clip; it can still be renamed, moved and deleted.

## Request body

- CreateMotionClipRequest: A new clip at the end of the video that plays a blank Tella Motion document of its own, as large as the video and `duration` seconds long (10 when absent), or your document `documentId`. Without `videoId`, a new video as large as that document. The clip lasts as long as its document.
  - `documentId` string: A Tella Motion document of yours that no video plays yet, for the clip to play instead of a blank one. The video takes it over.
  - `duration` number: How long the clip plays, in seconds (default 10): the blank document's canvas length. Not with `documentId`, whose document keeps its own length.
  - `name` string, required: The clip's name, and the new video's when there is no `videoId`.
  - `videoId` string: The video (vid_…) to add the clip to. Leave it out, with `documentId`, for a new video.

## Response `201`

Created

- MotionClipResponse: The new clip and the document it plays
  - `clipId` string, required
  - `document` MotionDocument, required: A Tella Motion document: a render timeline (a tree of media, sound, text, shape, sequence and composition nodes) that a Tella Motion clip, overlay or b-roll plays live, so edits show in the video at once.
    - `createdAt` string, required
    - `id` string, required: Document ID
    - `name` string, required
    - `ownerID` string, required: The owner's ID: the video's, for `story` documents; yours, for `user` documents.
    - `sceneID` string: The clip that plays this document, when it is a Tella Motion clip's. Absent for overlays and b-roll.
    - `scope` string, required: Who owns the document: `story` for a video's own documents (its Tella Motion clips, overlays and b-roll), `user` for one of yours that no video plays yet.
  - `editUrl` string: The new video in the Tella editor, when the clip made one.
  - `videoId` string: The new video, when the clip made one.

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

> 65 revisions in range; 1 not diffed.

- **2026-10-28** `dde1f23eeb8b`: 1 info
  - added the new optional request property `duration`
- **2026-10-27** `240a74ea0ff7`: 4 info
  - added the new optional request property `documentId`
  - the request property `videoId` became optional
  - added the optional property `editUrl` to the response with the `201` status
  - added the optional property `videoId` to the response with the `201` status
- **2026-10-22** `156b28c30e54`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/motion/clips/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/0cc3fcd307ad?raw)