List your videos

list_assetsGET/v1/assetsBeta

Lists the videos you uploaded or imported, 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 video to analyze: any of these ids can be the source of a project. The list holds the videos that came from you, through complete_upload (POST /v1/uploads/{uploadId}/complete), import_asset or the GPT-Video app. Files the service makes from them, such as converted copies and exports, are not listed; get_asset (GET /v1/assets/{assetId}) reads them by id. Use search to find a video by its title.

Example use

A script that watches a folder of new recordings lists the videos already uploaded and compares their file names with the files on disk. It uploads only the ones that are missing, then creates a project for each.

Endpoint

Code

GET https://api.gpt-video.com/v1/assets

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

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.
`search`	string	Optional	Return only the videos whose title contains this text, ignoring case. From 1 to 200 characters.

Request

List your videos.

curl

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

TypeScript

const res = await fetch("https://api.gpt-video.com/v1/assets", {
  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/assets",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "list_assets",
    "arguments": {}
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Name	Type	Description
`data[].id`	string	The asset id. It starts with ast_.
`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": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    },
    {
      "id": "ast_3f9a1c7e5b2d4086a1c4",
      "kind": "video",
      "title": "Interview with a founder",
      "filename": "interview.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 734003200,
      "durationSec": 1800,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "deletesAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

All response fields

Name	Type	Required	Description
`data`	array of objects	Required	The items of this page.
`data[].id`	string	Required	The asset id. It starts with ast_.
`data[].kind`	string	Required	One of `video`, `audio`, `image`, `font`, `other`.
`data[].title`	string	Required
`data[].filename`	string or null	Required	The name of the file as it was uploaded, when there was one.
`data[].origin`	string	Required	upload was sent by you, link was imported from a link, converted is a playable copy made for the analysis, export is the file of an export, voice is the audio of a voiceover, separated is the audio an audio separation kept. One of `upload`, `link`, `converted`, `export`, `voice`, `separated`.
`data[].mimeType`	string	Required
`data[].sizeBytes`	integer	Required
`data[].durationSec`	number or null	Required
`data[].width`	integer or null	Required	The width as the video is shown, rotation applied.
`data[].height`	integer or null	Required	The height as the video is shown, rotation applied.
`data[].fps`	number or null	Required
`data[].hasAudio`	boolean or null	Required
`data[].createdAt`	string	Required	An ISO 8601 time in UTC.
`data[].deletesAt`	string or null	Required	The first time the file may be deleted to free space: files are kept for a limited time. null when nothing deletes it.
`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

List your videos one at a time

GET /v1/assets?limit=1

HTTP 200

{
  "data": [
    {
      "id": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJrIjp7ImNyZWF0ZWRBdCI6IjIwMjYtMDktMDFUMDk6MDU6MDAuMDAwWiIsImlkIjoiYXN0XzhlMjFiMGQ5NGM2ZjRhMTdiMzU4In0sInYiOjF9"
}

Get the next page

GET /v1/assets?limit=1&cursor=eyJrIjp7ImNyZWF0ZWRBdCI6IjIwMjYtMDktMDFUMDk6MDU6MDAuMDAwWiIsImlkIjoiYXN0XzhlMjFiMGQ5NGM2ZjRhMTdiMzU4In0sInYiOjF9

HTTP 200

{
  "data": [
    {
      "id": "ast_3f9a1c7e5b2d4086a1c4",
      "kind": "video",
      "title": "Interview with a founder",
      "filename": "interview.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 734003200,
      "durationSec": 1800,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "deletesAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Find a video by its title

GET /v1/assets?search=demo

HTTP 200

{
  "data": [
    {
      "id": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Errors

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

Cost

No credits are used.

get_asset (GET /v1/assets/{assetId}) Get an asset
get_transcript (GET /v1/assets/{assetId}/transcript) Get the transcript of a video
create_project (POST /v1/projects) Create a project
separate_audio (POST /v1/audio-separations) Separate the voices of a video

Questions

Why is an export not in this list?

The list holds only the videos that came from you. The file of an export is read with get_asset (GET /v1/assets/{assetId}), by the id its export gives.

Does a video I uploaded in the app show up here?

Yes. Videos uploaded in the GPT-Video app and through the API are the same list. The background clips of the app's library are the one exception: they are not sources, and they are not listed.

View as Markdown

About

Example use

Endpoint

Parameters

Query

Request

Response

Fields to check

Response example

List your videos one at a time

Get the next page

Find a video by its title

Errors

Cost

Related operations

Questions

Why is an export not in this list?

Does a video I uploaded in the app show up here?