Update a split screen project

update_split_screen_projectPATCH/v1/projects/{projectId}/split-screenBeta

Changes the name, the layout, the captions, the start of the background or the vocabulary of a split screen project.

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

Only the fields you send change. The changes are used by the next build, which is charged; a change saved while a build waits in the queue is read by that build. The two videos and the language cannot be changed: sending them is refused, and to use other videos you create another project.

Example use

A script changes the layout and the captions of a project after a first build looked crowded. It builds the video again with build_split_screen_video (POST /v1/projects/{projectId}/split-screen/build) once the settings are right.

Endpoint

Code

PATCH https://api.gpt-video.com/v1/projects/{projectId}/split-screen

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.
No Idempotency-Key.

Parameters

Path

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

Body

The body is optional. Send only the fields you want to change.

Name	Type	Required	Description
`title`	string	Optional	The new name of the project. From 1 to 120 characters. Matches `\S`.
`layout`	string	Optional	How the screen is split: 50-50 gives each video half the screen, 60-40 gives the main video more. One of `50-50`, `60-40`.
`captionStyle`	string or null	Optional	The caption style, or null for a video with no captions. get_setting_options (`GET /v1/reference/setting-options`) lists every style with what it looks like. One of `bold-karaoke`, `word-pop`, `boxed`, `outline`.
`backgroundStartSec`	number or null	Optional	Where the background video starts, in seconds; null lets the next build choose a random start, which is then kept. At least 0.
`vocabulary`	string or null	Optional	Names, brands and jargon the transcription should spell right, separated by commas. At most 311 characters; null removes it. At most 311 characters.

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

Request

Change the layout and the start of the background.

curl

curl -X PATCH "https://api.gpt-video.com/v1/projects/prj_9cf6ba9cd17fd89cf513/split-screen" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "layout": "50-50",
    "backgroundStartSec": 12
  }'

TypeScript

const res = await fetch("https://api.gpt-video.com/v1/projects/prj_9cf6ba9cd17fd89cf513/split-screen", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "layout": "50-50",
    "backgroundStartSec": 12
  }),
});
const data = await res.json();
console.log(data);

Python

import os

import requests

r = requests.patch(
    "https://api.gpt-video.com/v1/projects/prj_9cf6ba9cd17fd89cf513/split-screen",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
    json={
        "layout": "50-50",
        "backgroundStartSec": 12
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "update_split_screen_project",
    "arguments": {
      "projectId": "prj_9cf6ba9cd17fd89cf513",
      "layout": "50-50",
      "backgroundStartSec": 12
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Project object in project.

Fields to check

Name	Type	Description
`project.id`	string	The project id. It starts with prj_.
`project.status`	string	draft has not been analyzed yet, processing is being analyzed, ready has clips, failed means the last analysis failed and errorMessage says why.

Response example

HTTP 200

{
  "project": {
    "id": "prj_9cf6ba9cd17fd89cf513",
    "kind": "splitscreen",
    "title": "Founder interview, split",
    "status": "ready",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "compositionId": "cmp_cc26cb47fd6004aa5fba",
    "settings": null,
    "missingSettings": [],
    "errorMessage": null,
    "splitScreen": {
      "mainAssetId": "ast_3f9a1c7e5b2d4086a1c4",
      "backgroundAssetId": "ast_8ac5d8b97546145cdbf6",
      "layout": "50-50",
      "captionStyle": "bold-karaoke",
      "language": "en",
      "backgroundStartSec": 12,
      "vocabulary": null
    },
    "streamer": null,
    "redditStory": null,
    "fakeText": null,
    "vibeEdit": null,
    "createdAt": "2026-08-31T21:40:00.000Z",
    "updatedAt": "2026-09-01T11:05:00.000Z"
  }
}

All response fields

Name	Type	Required	Description
`project`	Project object	Required	Described in Project object.

More examples

Remove the captions

PATCH /v1/projects/prj_9cf6ba9cd17fd89cf513/split-screen

Request body

{
  "captionStyle": null
}

HTTP 200

{
  "project": {
    "id": "prj_9cf6ba9cd17fd89cf513",
    "kind": "splitscreen",
    "title": "Founder interview, split",
    "status": "ready",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "compositionId": "cmp_cc26cb47fd6004aa5fba",
    "settings": null,
    "missingSettings": [],
    "errorMessage": null,
    "splitScreen": {
      "mainAssetId": "ast_3f9a1c7e5b2d4086a1c4",
      "backgroundAssetId": "ast_8ac5d8b97546145cdbf6",
      "layout": "60-40",
      "captionStyle": null,
      "language": "en",
      "backgroundStartSec": null,
      "vocabulary": null
    },
    "streamer": null,
    "redditStory": null,
    "fakeText": null,
    "vibeEdit": null,
    "createdAt": "2026-08-31T21:40:00.000Z",
    "updatedAt": "2026-09-01T11:05:00.000Z"
  }
}

A project of another kind

PATCH /v1/projects/prj_7c2e9a4f1b3d4e8096a5/split-screen

Request body

{
  "layout": "50-50"
}

HTTP 409

{
  "error": {
    "code": "CONFLICT",
    "message": "This project is not a split screen project. Use the operations of its kind, or analyze_project for an Auto Clip project.",
    "requestId": "req_4a0d7e2b9c1f63e85b2a0d14"
  }
}

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	See the error reference.	Change the request, then send it again.
`CONFLICT`	409	A project of another kind	Read the resource again, then decide. Do not send the same request again.

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, PAYLOAD_TOO_LARGE, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used. The next build is charged when you call build_split_screen_video (POST /v1/projects/{projectId}/split-screen/build).

create_split_screen_project (POST /v1/projects/split-screen) Create a split screen project
build_split_screen_video (POST /v1/projects/{projectId}/split-screen/build) Build a split screen video
get_project (GET /v1/projects/{projectId}) Get a project

Questions

Why is mainAssetId refused here?

The videos of a split screen project are chosen when it is created and never change, because the price depends on them. Create another project to use other videos.

When do my changes show in the video?

At the next build. build_split_screen_video (POST /v1/projects/{projectId}/split-screen/build) makes the video again with the settings saved at the moment the build starts.

View as Markdown