Change an edit

apply_timeline_operationsPOST/v1/projects/{projectId}/timeline/operationsBeta

Applies a list of operations to an edit in one change: cuts, order, transitions, zoom, sound, captions, texts, b-roll, music and shape.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

About

Send the revision you read with get_timeline (GET /v1/projects/{projectId}/timeline) and from 1 to 50 operations: they apply in order, as one change and one new revision, or not at all. Segments, texts and b-roll are named by the ids get_timeline shows; times of segments are seconds of the source video, times of texts and b-roll are seconds of the video that comes out. Adding a video is not an operation here, because it costs credits: use add_timeline_clip (POST /v1/projects/{projectId}/timeline/clips). The answer is the edit after the change, with warnings that say what was adjusted.

Example use

An editing tool lets a person remove a long pause and add a title text. It sends both as one list of operations with the revision it read, then shows the warnings of the answer next to the new edit.

Endpoint

Code

POST https://api.gpt-video.com/v1/projects/{projectId}/timeline/operations

Scope clips:write.
Rate limit 60 requests a minute for each key and 120 for each account, shared by every write call. See rate limits.
Idempotency-Key is optional.

Parameters

Path

Name	Type	Required	Description
`projectId`	string	Required	The project id. It starts with prj_. Matches `^prj_[0-9a-f]{20}$`.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	Optional	Send the same key on every retry of this request. From 1 to 255 visible characters, such as a UUID. See idempotency.

Body

Name	Type	Required	Description
`expectedRevision`	integer	Required	The revision of the edit you read last, from get_timeline (`GET /v1/projects/{projectId}/timeline`) or from the answer of your last change. If the edit changed since then, nothing is written and the answer is CONFLICT. At least 0.
`operations`	array of objects	Required	The operations, from 1 to 50, applied in this order. The op field says which one each is. From 1 to 50 items.

Each item of operations is one of 21 variants, chosen by op. Send exactly one variant for each item.

op = "split_segment"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `split_segment`.
`operations[].segmentId`	string	Required	The segment id. It starts with seg_. Matches `^seg_[0-9a-f]{20}$`.
`operations[].atSourceSec`	number	Required	Where to cut, in seconds of the source video. More than 0.

op = "trim_segment"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `trim_segment`.
`operations[].segmentId`	string	Required	The segment id. It starts with seg_. Matches `^seg_[0-9a-f]{20}$`.
`operations[].sourceStartSec`	number	Optional	The new start, in seconds of the source video. At least 0.
`operations[].sourceEndSec`	number	Optional	The new end, in seconds of the source video. More than 0.

op = "remove_segments"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `remove_segments`.
`operations[].segmentIds`	array of strings	Required	The segment ids, from 1 to 200. From 1 to 200 items.

op = "move_segment"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `move_segment`.
`operations[].segmentId`	string	Required	The segment id. It starts with seg_. Matches `^seg_[0-9a-f]{20}$`.
`operations[].beforeSegmentId`	string or null	Required	The segment to move it in front of; null moves it to the end. Matches `^seg_[0-9a-f]{20}$`.

op = "set_transition"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_transition`.
`operations[].segmentId`	string	Required	The segment id. It starts with seg_. Matches `^seg_[0-9a-f]{20}$`.
`operations[].kind`	string	Required	One of `dip`, `dissolve`.
`operations[].sec`	number	Required	How long the transition into this segment lasts, from 0 to 3 seconds; 0 removes it. From 0 to 3.

op = "set_video_fade"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_video_fade`.
`operations[].edge`	string	Required	One of `start`, `end`.
`operations[].sec`	number	Required	How long the fade lasts, from 0 to 3 seconds; 0 removes it. From 0 to 3.

op = "set_zoom"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_zoom`.
`operations[].segmentIds`	array of strings	Required	The segment ids, from 1 to 200. From 1 to 200 items.
`operations[].factor`	number	Required	1 removes the zoom; up to 1.5. From 1 to 1.5.
`operations[].mode`	string	Required	One of `static`, `push`.

op = "set_segment_audio"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_segment_audio`.
`operations[].segmentIds`	array of strings	Required	The segment ids, from 1 to 200. From 1 to 200 items.
`operations[].volume`	number	Optional	From 0 to 2.
`operations[].muted`	boolean	Optional

op = "remove_silences"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `remove_silences`.
`operations[].aggressiveness`	string	Required	One of `soft`, `standard`, `aggressive`.

op = "remove_fillers"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `remove_fillers`.

op = "set_captions"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_captions`.
`operations[].enabled`	boolean	Optional
`operations[].style`	string	Optional	One of `bold-karaoke`, `word-pop`, `boxed`, `outline`.
`operations[].options`	object	Optional	The caption options to change. A field you leave out stays as it is.
`operations[].options.fontFamily`	string	Optional	The typeface of the captions. One of `Montserrat`, `Anton`, `System`.
`operations[].options.fontSize`	integer	Optional	The size of the caption text, from 20 to 200. From 20 to 200.
`operations[].options.yPercent`	number	Optional	Where the captions sit, from 0 at the top to 100 at the bottom. From 0 to 100.
`operations[].options.color`	string	Optional	The color of the words, as #RRGGBB. Matches `^#[0-9A-Fa-f]{6}$`.
`operations[].options.highlightColor`	string	Optional	The color of the word being spoken, as #RRGGBB. Matches `^#[0-9A-Fa-f]{6}$`.
`operations[].options.maxWordsPerGroup`	integer	Optional	How many words are on screen at once, at most, from 1 to 12. From 1 to 12.
`operations[].options.maxCharsPerGroup`	integer	Optional	How many characters are on screen at once, at most, from 4 to 80. From 4 to 80.
`operations[].options.uppercase`	boolean	Optional	true shows the captions in capital letters.
`operations[].options.maxGapSec`	number	Optional	The longest pause, in seconds, inside one group of words on screen, from 0.1 to 5. From 0.1 to 5.

op = "replace_caption_word"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `replace_caption_word`.
`operations[].from`	string	Required	From 1 to 200 characters.
`operations[].to`	string	Required	From 1 to 200 characters.
`operations[].occurrence`	integer	Optional	Which match to replace, from 1; leave it out to replace every match. At least 1.

op = "add_text"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `add_text`.
`operations[].text`	string	Required	From 1 to 200 characters.
`operations[].preset`	string	Required	One of `headline`, `hook`, `caption-note`.
`operations[].outputStartSec`	number	Required	A time in the video that comes out, in seconds. At least 0.
`operations[].durationSec`	number	Required	A length in seconds. More than 0.
`operations[].xPercent`	number	Optional	The horizontal position, from 0 to 100. From 0 to 100.
`operations[].yPercent`	number	Optional	The vertical position, from 0 to 100. From 0 to 100.

op = "update_text"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `update_text`.
`operations[].textId`	string	Required	The text id. It starts with ovl_. Matches `^ovl_[0-9a-f]{20}$`.
`operations[].text`	string	Optional	From 1 to 200 characters.
`operations[].preset`	string	Optional	One of `headline`, `hook`, `caption-note`.
`operations[].outputStartSec`	number	Optional	A time in the video that comes out, in seconds. At least 0.
`operations[].durationSec`	number	Optional	A length in seconds. More than 0.
`operations[].xPercent`	number or null	Optional	The horizontal position, from 0 to 100. From 0 to 100.
`operations[].yPercent`	number or null	Optional	The vertical position, from 0 to 100. From 0 to 100.

op = "remove_text"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `remove_text`.
`operations[].textId`	string	Required	The text id. It starts with ovl_. Matches `^ovl_[0-9a-f]{20}$`.

op = "add_broll"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `add_broll`.
`operations[].assetId`	string	Required	Matches `^ast_n?[0-9a-f]{20}$`.
`operations[].outputStartSec`	number	Required	A time in the video that comes out, in seconds. At least 0.
`operations[].durationSec`	number	Required	A length in seconds. More than 0.
`operations[].fit`	string	Required	One of `cover`, `contain`.

op = "update_broll"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `update_broll`.
`operations[].brollId`	string	Required	The b-roll id. It starts with brl_. Matches `^brl_[0-9a-f]{20}$`.
`operations[].outputStartSec`	number	Optional	A time in the video that comes out, in seconds. At least 0.
`operations[].durationSec`	number	Optional	A length in seconds. More than 0.
`operations[].fit`	string	Optional	One of `cover`, `contain`.

op = "remove_broll"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `remove_broll`.
`operations[].brollId`	string	Required	The b-roll id. It starts with brl_. Matches `^brl_[0-9a-f]{20}$`.

op = "set_music"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_music`.
`operations[].assetId`	string or null	Required	The music file; null removes the music. Matches `^ast_n?[0-9a-f]{20}$`.
`operations[].volume`	number	Optional	From 0 to 0.5.

op = "set_aspect"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_aspect`.
`operations[].aspect`	string	Required	One of `source`, `9:16`, `1:1`, `16:9`.

op = "set_reframe"

Name	Type	Required	Description
`operations[].op`	string	Required	Always `set_reframe`.
`operations[].mode`	string	Required	One of `off`, `face`, `center`.

Send only the fields listed here. Any other field is refused with UNKNOWN_PARAMETER.

Request

Cut a segment in two and remove another.

curl

# Create the key once. Send this same key again if you retry this request.
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/operations" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedRevision": 1,
    "operations": [
      {
        "op": "split_segment",
        "segmentId": "seg_7279fbb508f4a22e65a4",
        "atSourceSec": 135
      },
      {
        "op": "remove_segments",
        "segmentIds": [
          "seg_a9dcee59c1fb9edb6751"
        ]
      }
    ]
  }'

TypeScript

// Create the key once. Send this same key again if you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/operations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "expectedRevision": 1,
    "operations": [
      {
        "op": "split_segment",
        "segmentId": "seg_7279fbb508f4a22e65a4",
        "atSourceSec": 135
      },
      {
        "op": "remove_segments",
        "segmentIds": [
          "seg_a9dcee59c1fb9edb6751"
        ]
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

Python

import os
import uuid

import requests

# Create the key once. Send this same key again if you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.post(
    "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/operations",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={
        "expectedRevision": 1,
        "operations": [
            {
                "op": "split_segment",
                "segmentId": "seg_7279fbb508f4a22e65a4",
                "atSourceSec": 135
            },
            {
                "op": "remove_segments",
                "segmentIds": [
                    "seg_a9dcee59c1fb9edb6751"
                ]
            }
        ]
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "apply_timeline_operations",
    "arguments": {
      "projectId": "prj_b9c1f9c7873dcef51a57",
      "expectedRevision": 1,
      "operations": [
        {
          "op": "split_segment",
          "segmentId": "seg_7279fbb508f4a22e65a4",
          "atSourceSec": 135
        },
        {
          "op": "remove_segments",
          "segmentIds": [
            "seg_a9dcee59c1fb9edb6751"
          ]
        }
      ]
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Timeline object in timeline.

Fields to check

Name	Type	Description
`timeline.id`	string	The edit id. It starts with tml_.
`timeline.segments[].id`	string	The segment id. It starts with seg_.
`timeline.texts[].id`	string	The text id. It starts with ovl_.
`timeline.broll[].id`	string	The b-roll id. It starts with brl_.

Response example

HTTP 200

{
  "timeline": {
    "id": "tml_bbe061171a8229f8daed",
    "projectId": "prj_b9c1f9c7873dcef51a57",
    "compositionId": "cmp_cfbdd85eaaff301fa997",
    "revision": 2,
    "durationSec": 30,
    "aspect": "9:16",
    "reframe": "off",
    "captions": {
      "enabled": true,
      "style": "bold-karaoke"
    },
    "music": null,
    "fadeInSec": 0,
    "fadeOutSec": 0,
    "clips": [
      {
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "title": "Interview with a founder",
        "durationSec": 1800,
        "state": "ready"
      }
    ],
    "segments": [
      {
        "id": "seg_7279fbb508f4a22e65a4",
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "sourceStartSec": 120,
        "sourceEndSec": 135,
        "zoom": 1,
        "muted": false,
        "volume": 1,
        "outputStartSec": 0,
        "outputEndSec": 15
      },
      {
        "id": "seg_5a0e3c8f1d7b42e69c13",
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "sourceStartSec": 135,
        "sourceEndSec": 150,
        "zoom": 1,
        "muted": false,
        "volume": 1,
        "outputStartSec": 15,
        "outputEndSec": 30
      }
    ],
    "texts": [
      {
        "id": "ovl_49f5239b9cd73496225d",
        "text": "Paid before the product",
        "preset": "headline",
        "outputStartSec": 0,
        "durationSec": 3,
        "xPercent": null,
        "yPercent": null
      }
    ],
    "broll": [
      {
        "id": "brl_f44d18e008ec4009bf10",
        "assetId": "ast_8ac5d8b97546145cdbf6",
        "outputStartSec": 12,
        "durationSec": 4,
        "fit": "cover"
      }
    ],
    "diagnostics": []
  },
  "compositionId": "cmp_cfbdd85eaaff301fa997",
  "warnings": []
}

All response fields

Name	Type	Required	Description
`timeline`	Timeline object	Required	Described in Timeline object.
`compositionId`	string	Required	The composition the edit compiles to, to export with create_export (`POST /v1/compositions/{compositionId}/exports`).
`warnings`	array of strings	Required	What the change adjusted or could not do, in one sentence each; empty when nothing.

More examples