JSON2VIDEO Documentation List media
GET https://api.json2video.com/v2/media
The media resource has three sub-paths:
GET /v2/media— storage info (used bytes, free allowance, billing state).GET /v2/media/file— single file metadata.GET /v2/media/folder— folder listing (contents or tree).
All sub-paths require the x-api-key header with role render, editor, manager, or admin.
Request — storage info
Path
GET /v2/media
Query parameters
None.
Response — storage info
200 OK
{
"success": true,
"storage": {
"used_bytes": 12582912,
"free_allowance": 52428800,
"credits_per_week": 0,
"blocked": false,
"blocked_at": null
}
}
| Field | Type | Description |
|---|---|---|
used_bytes |
integer | Total bytes used by the account's non-temporary files. |
free_allowance |
integer | Bytes included for free. Currently 50 MB. |
credits_per_week |
integer | Weekly credit consumption based on usage above the free allowance (10 credits per GiB-week, rounded up). |
blocked |
boolean | When true, uploads are rejected. |
blocked_at |
string|null | ISO-8601 timestamp at which storage was blocked. |
Request — single file
Path
GET /v2/media/file
Query parameters
| Parameter | Type | Description |
|---|---|---|
path |
string | Required. Path of the file, e.g. videos/clip.mp4. |
Response — single file
200 OK
{
"success": true,
"file": {
"name": "clip.mp4",
"folder": "videos",
"type": "video",
"contentType": "video/mp4",
"size": 3145728,
"url": "https://media.json2video.com/{client_id}/files/videos/clip.mp4",
"thumbnailUrl": null,
"status": "uploaded",
"temporary": false,
"created_at": "2026-04-12T08:15:00.000Z"
}
}
type is one of image, video, audio, other. status is pending (awaiting upload) or uploaded.
Request — folder
Path
GET /v2/media/folder
Query parameters
| Parameter | Type | Description |
|---|---|---|
path / folder |
string | Folder to list. Default: /. |
tree |
string | true returns a flat list of folders with per-folder stats; default returns folder contents. |
type |
string | Filter by media type: image, video, audio, other. |
q |
string | Filename substring filter (case-insensitive). |
page |
integer | Zero-based page index. Default: 0. |
page_size |
integer | Items per page. Default: 20. |
Response — folder contents
200 OK — contents
{
"success": true,
"path": "videos",
"total_size": 8388608,
"total_files": 4,
"total": 4,
"page": 0,
"page_size": 20,
"folders": ["raw"],
"files": [
{
"name": "clip.mp4",
"folder": "videos",
"type": "video",
"contentType": "video/mp4",
"size": 3145728,
"url": "https://media.json2video.com/{client_id}/files/videos/clip.mp4",
"thumbnailUrl": null,
"status": "uploaded",
"created_at": "2026-04-12T08:15:00.000Z"
}
]
}
200 OK — tree
{
"success": true,
"tree": [
{ "path": "/", "files": 2, "size": 1048576 },
{ "path": "temp", "files": 0, "size": 0 },
{ "path": "videos", "files": 4, "size": 8388608 }
]
}
Errors
| Status | Message | Cause |
|---|---|---|
400 |
path is required |
Missing path on GET /v2/media/file. |
400 |
Invalid path: no filename |
path does not contain a filename. |
403 |
Insufficient permissions |
API key role is below render. |
404 |
File not found |
Path does not exist in the account. |
Examples
Storage usage
curl --location --request GET 'https://api.json2video.com/v2/media' \
--header 'x-api-key: YOUR_API_KEY'
List a folder
curl --location --request GET \
'https://api.json2video.com/v2/media/folder?path=videos&page=0&page_size=50' \
--header 'x-api-key: YOUR_API_KEY'
Folder tree
curl --location --request GET \
'https://api.json2video.com/v2/media/folder?tree=true' \
--header 'x-api-key: YOUR_API_KEY'
Single file
curl --location --request GET \
'https://api.json2video.com/v2/media/file?path=videos/clip.mp4' \
--header 'x-api-key: YOUR_API_KEY'