List the compositions of a project

list_compositionsGET/v1/projects/{projectId}/compositionsBeta

Lists the compositions of a project, the newest first, a page at a time.

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

Use it to find the composition of a project of any kind: an Auto Clip project has one for each accepted clip, and a split screen, streamer, Reddit story, fake text or Vibe Editing project has one, which is also its compositionId. Then read it with get_composition (GET /v1/compositions/{compositionId}), change it with edit_composition (POST /v1/compositions/{compositionId}/edit) or export it with create_export (POST /v1/compositions/{compositionId}/exports). Pass the nextCursor of a page to get the next one.

Example use

A dashboard for a social media manager lists the compositions of a project to show which clips were accepted. A click on one opens it with get_composition (GET /v1/compositions/{compositionId}), where the manager can edit or export it.

Endpoint

Code

GET https://api.gpt-video.com/v1/projects/{projectId}/compositions

Scope clips:read.
Rate limit 120 requests a minute for each key and 240 for each account, shared by every read call. See rate limits.
No Idempotency-Key.

Parameters

Path

Name	Type	Required	Description
`projectId`	string	Required	The id of the project, as create_project (`POST /v1/projects`) returns it. Matches `^prj_[0-9a-f]{20}$`.

Query

Name	Type	Required	Description
`limit`	integer	Optional	How many items to return, from 1 to 100. Defaults to 20. From 1 to 100. Default `20`.
`cursor`	string	Optional	The nextCursor value from the previous page. Leave it out to get the first page. From 1 to 512 characters.

Request

List the compositions of an Auto Clip project.

curl

curl "https://api.gpt-video.com/v1/projects/prj_7c2e9a4f1b3d4e8096a5/compositions" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

TypeScript

const res = await fetch("https://api.gpt-video.com/v1/projects/prj_7c2e9a4f1b3d4e8096a5/compositions", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Python

import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/projects/prj_7c2e9a4f1b3d4e8096a5/compositions",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "list_compositions",
    "arguments": {
      "projectId": "prj_7c2e9a4f1b3d4e8096a5"
    }
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Name	Type	Description
`data[].id`	string	The composition id. It starts with cmp_.
`data[].framing.status`	string
`data[].framing.jobId`	string or null
`hasMore`	boolean	true when there are more items after this page.
`nextCursor`	string or null	Send it as cursor to get the next page. It is null on the last page.

Response example

HTTP 200

{
  "data": [
    {
      "id": "cmp_1e710123e428fb030a18",
      "projectId": "prj_7c2e9a4f1b3d4e8096a5",
      "clipId": "cnd_8e77645e55cc8ea02336",
      "kind": "autoclip",
      "title": "Selling the idea first",
      "revision": 0,
      "durationSec": 35,
      "width": 1080,
      "height": 1920,
      "fps": 30,
      "source": {
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "startSec": 900,
        "endSec": 935
      },
      "hook": "Sell it before you build it",
      "captions": {
        "style": "word-pop",
        "wordCount": 87
      },
      "framing": {
        "status": "centered",
        "jobId": null
      },
      "createdAt": "2026-09-01T10:02:00.000Z",
      "updatedAt": "2026-09-01T10:02:00.000Z"
    },
    {
      "id": "cmp_4e8c2a6f09d14b73a1e5",
      "projectId": "prj_7c2e9a4f1b3d4e8096a5",
      "clipId": "cnd_9e04a6c3d12b4f78a5b9",
      "kind": "autoclip",
      "title": "Paid before the product",
      "revision": 0,
      "durationSec": 30,
      "width": 1080,
      "height": 1920,
      "fps": 30,
      "source": {
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "startSec": 120,
        "endSec": 150
      },
      "hook": "They paid us before we had a product",
      "captions": {
        "style": "word-pop",
        "wordCount": 75
      },
      "framing": {
        "status": "centered",
        "jobId": null
      },
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

All response fields

Name	Type	Required	Description
`data`	array of objects	Required	The items of this page.
`data[]`	Composition object	Optional	Described in Composition object.
`hasMore`	boolean	Required	true when there are more items after this page.
`nextCursor`	string or null	Required	Send it as cursor to get the next page. It is null on the last page.

More examples

Find the composition of a split screen project

GET /v1/projects/prj_9cf6ba9cd17fd89cf513/compositions

HTTP 200

{
  "data": [
    {
      "id": "cmp_cc26cb47fd6004aa5fba",
      "projectId": "prj_9cf6ba9cd17fd89cf513",
      "clipId": null,
      "kind": "splitscreen",
      "title": "Founder interview, split",
      "revision": 0,
      "durationSec": 1800,
      "width": 1080,
      "height": 1920,
      "fps": 30,
      "source": null,
      "hook": null,
      "captions": {
        "style": "bold-karaoke",
        "wordCount": 380
      },
      "framing": {
        "status": "none",
        "jobId": null
      },
      "createdAt": "2026-08-31T21:46:00.000Z",
      "updatedAt": "2026-08-31T21:46:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

A project that does not exist

GET /v1/projects/prj_9f0d3b7e1c5a4d28b6f3/compositions

HTTP 404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project prj_9f0d3b7e1c5a4d28b6f3 not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_0d7b3e9a5c1f46e2b8a4d6c0"
  }
}

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	A project that does not exist	Change the request, then send it again.

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

Cost

No credits are used.

get_composition (GET /v1/compositions/{compositionId}) Get a composition
edit_composition (POST /v1/compositions/{compositionId}/edit) Edit a composition
create_export (POST /v1/compositions/{compositionId}/exports) Export a composition
get_project (GET /v1/projects/{projectId}) Get a project
delete_composition (DELETE /v1/compositions/{compositionId}) Delete a composition

Questions

Why does my split screen project show one composition only?

A split screen, streamer, Reddit story, fake text or Vibe Editing project has one composition, made by its build or its preparation. Only an Auto Clip project has one for each accepted clip.

Why is the list of a new project empty?

A composition exists once a clip is accepted, or once the project is built or prepared. Until then the project has none.

View as Markdown