Get an asset

get_assetGET/v1/assets/{assetId}Beta

Returns one file: a video you uploaded, its converted copy, or the file of an export.

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 read the size, length and dimensions of a file, and when it may be deleted. Files are kept for a limited time; see deletesAt. After an analysis the sourceAssetId of a project can point to the converted copy of its video, whose id starts with ast_n: this operation reads that copy too.

Example use

Before it creates a split screen project, a script reads the two uploaded videos here. It checks that the main video has sound and shows the length of each one to the person who picked them.

Endpoint

Code

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

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
`assetId`	string	Required	The id of the asset. It starts with ast_, or with ast_n for the converted copy an analysis makes. Matches `^ast_n?[0-9a-f]{20}$`.

Request

Read a video you uploaded.

curl

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

TypeScript

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

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "get_asset",
    "arguments": {
      "assetId": "ast_3f9a1c7e5b2d4086a1c4"
    }
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Name	Type	Description
`asset.id`	string	The asset id. It starts with ast_.

Response example

HTTP 200

{
  "asset": {
    "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
  }
}

All response fields

Name	Type	Required	Description
`asset`	object	Required
`asset.id`	string	Required	The asset id. It starts with ast_.
`asset.kind`	string	Required	One of `video`, `audio`, `image`, `font`, `other`.
`asset.title`	string	Required
`asset.filename`	string or null	Required	The name of the file as it was uploaded, when there was one.
`asset.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`.
`asset.mimeType`	string	Required
`asset.sizeBytes`	integer	Required
`asset.durationSec`	number or null	Required
`asset.width`	integer or null	Required	The width as the video is shown, rotation applied.
`asset.height`	integer or null	Required	The height as the video is shown, rotation applied.
`asset.fps`	number or null	Required
`asset.hasAudio`	boolean or null	Required
`asset.createdAt`	string	Required	An ISO 8601 time in UTC.
`asset.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.

More examples

Read the file of an export

GET /v1/assets/ast_c47d2e8a19b54f06d2e1

HTTP 200

{
  "asset": {
    "id": "ast_c47d2e8a19b54f06d2e1",
    "kind": "video",
    "title": "Paid before the product",
    "filename": null,
    "origin": "export",
    "mimeType": "video/mp4",
    "sizeBytes": 18874368,
    "durationSec": 30,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "hasAudio": true,
    "createdAt": "2026-09-01T10:15:00.000Z",
    "deletesAt": "2026-09-15T10:15:00.000Z"
  }
}

Read an asset that does not exist

GET /v1/assets/ast_0b1e5c9d3a7f40628e2d

HTTP 404

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

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	Read an asset 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.

list_assets (GET /v1/assets) List your videos
get_transcript (GET /v1/assets/{assetId}/transcript) Get the transcript of a video
create_project (POST /v1/projects) Create a project
create_upload (POST /v1/uploads) Start an upload
complete_upload (POST /v1/uploads/{uploadId}/complete) Complete an upload
create_voiceover (POST /v1/voiceovers) Create a voiceover

Questions

What does deletesAt mean?

It is the first time the file may be deleted to free space. It is null when nothing deletes the file, for example while a project still uses it.

What is an asset with origin converted?

A copy of one of your videos in a format every step can play, made when the video is analyzed. It belongs to the same video and is never listed on its own.

View as Markdown