Read an asset
read_assetRead an uploaded asset's pixels, metadata and readiness: its size, length, frame rate and whether a video has a sound track (hasAudio), with the image, a timestamped contact sheet of a video, or a sound's waveform. For what a file says or where its shots and beats are, use transcribe_asset and read_transcript, detect_scenes and detect_beats; search_video_moments finds moments by what they show or say. id is an Asset ID from search_assets, or a Library id from search_library or search_video_moments: a Library file is read where it is, without adding it to a project, with or without one open. To look closely at a video file, whether or not it is on the film (preview_frame and preview_range draw only the film): startSeconds and endSeconds draw a contact sheet of only that range of the file, and times draws up to 4 frames of the file large. Use them to time an action to a tenth of a second or to check a detail. box draws only part of the frame (or of an image) from the full-resolution file: use it to read a label, a screen, small text or a face, and to check what a cover must hide. A sound draws as its waveform over its spectrum, with its loudest moment and its beats; startSeconds and endSeconds draw only that part, to find a hit or a silence to cut on. A 3D model draws from four sides, with the materials its file names. A call with a range, times or box answers with the picture and its legend, not the record.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"id": "<id>",
"startSeconds": "<startSeconds>",
"endSeconds": "<endSeconds>",
"times": "<times>",
"box": "<box>",
"space": "<space>",
"previewId": "<previewId>",
"clipId": "<clipId>",
"atSpace": "<atSpace>",
"projectId": "<projectId>"
},
"name": "read_asset"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| box | Yes | Part of the file to draw, as [x0, y0, x1, y1] in the file's own pixels (its width and height, the pixels find_objects and track_box give boxes in): the top left and bottom right corners. Works with times, with a range, alone for the whole video, and on an image. The box is cut from the full-resolution file, not from a preview, and drawn large, so small text, labels, screens and faces read. The answer gives the scale from the picture's pixels back to the file's. With space preview and previewId, the box is pixels of that preview and is read back as the file's pixels it shows. null (or leaving it out) draws the whole frame. | |
| space | Yes | The space of this call's coordinates. null or source: pixels of the asset file. preview: pixels of a preview image you were shown, with previewId; its time is that preview's time. film: scene pixels from the frame's centre; film_norm: 0 to 1 of the frame; clip: the clip's own picture (with clipId). The tool converts them to the asset's pixels through the film's real transforms. | |
| times | Yes | Seconds of a video file to see as large frames, 1 to 4, in one picture in time order with each time on its frame. Use it to check a detail or the exact moment of an action. Not with startSeconds and endSeconds. null (or leaving it out) draws a contact sheet. | |
| clipId | Yes | The film clip that plays this asset, when space or atSpace needs one and several clips play it. null picks the clip that shows the asset at that time. | |
| atSpace | Yes | What this call's times are. null or source: seconds into the asset file. timeline: seconds of the film, read through the clip that plays the asset then (clipId to pick one). | |
| previewId | Yes | With space preview or preview_norm: the previewId the preview_frame, preview_range or preview_timeline answer printed. Else null. | |
| projectId | Yes | The project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs. | |
| endSeconds | Yes | Where that range ends, in seconds of the file, after startSeconds. A video's sheet has up to 16 tiles with their times, so a range of 2 seconds shows a tile about every 0.13 seconds; a sound's strip spreads the range over its whole width. A range past the end of the file stops at its end. | |
| startSeconds | Yes | Where a contact sheet of part of a video, or the waveform and spectrum of part of a sound, starts, in seconds of the file. Pass it with endSeconds. null (or leaving it out) draws the whole file. |