Media uploads and inspection
Upload reusable images, video, audio and fonts before referencing them from projects and templates.
Multipart upload
curl -X POST "$JSONCUT_API/api/v2/media" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-F "file=@./product-demo.mp4" \
-F "retention=project" \
-F "projectId=$PROJECT_ID"Persist the returned reference, such as jsoncut-media://media_01J..., in project source. Preview URLs are short lived and must not be stored in a template.
Retention
| Value | Use | How long it stays |
|---|---|---|
temporary | Bulk inputs, one-off inline renders, drafts. | 48 hours; the response carries expiresAt. |
project | Files of one project. Requires projectId. | Until it is removed from the project's files in Studio or the project is deleted, then 7 more days. A save never removes a file from the project, even when no layer uses it. |
template | Files a template needs. Requires templateId. | While the template uses it, then 7 more days. |
persistent | The workspace library, usable in every project. | Until you delete it. PATCH /media/{id} with {"retention":"persistent"} keeps any file there. |
Every way in takes retention, so temporary stays available everywhere: uploads, upload tickets (retention: "temporary" without a project), URL imports and stock imports. Defaults: with projectId it is project, with templateId template, otherwise persistent; exports and review renders are always temporary. GET /media?library=true lists the library.
Small Base64 input
POST /api/v2/media also accepts an application/json body with a Base64 data: URL. This is convenient for tiny generated assets, but the JSON request has a strict size limit. On PAYLOAD_TOO_LARGE, upload multipart media and use the returned reference.
Import a public URL
curl -X POST "$JSONCUT_API/api/v2/media/import-url" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sourceUrl":"https://cdn.example.com/product.jpg","name":"Product photo","kind":"image","mimeType":"image/jpeg","retention":"project","projectId":"'"$PROJECT_ID"'"}'The importer rejects private-network targets, unsafe redirects, unsupported content and mismatched MIME types.
Inspect metadata
curl -X POST "$JSONCUT_API/api/v2/media/inspect" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mediaId":"media_01J..."}'Inspection returns useful, safe properties such as dimensions, duration, streams, codec and audio metadata. Use GET /api/v2/media/{id}/content for byte-range playback or download.
Studio resumable uploads are intentionally not public developer endpoints. Server integrations use the bounded upload shown here; MCP Agents can request one-use upload tickets without exposing storage credentials.
Limits, formats and storage
| Route | Per file | Formats |
|---|---|---|
POST /api/v2/media (multipart) | 100 MB | JPEG, PNG, GIF, WebP, SVG, MP4, MOV, WebM, MP3, WAV, M4A, AAC, fonts (WOFF2, WOFF, TTF, OTF) and Lottie JSON |
| MCP upload ticket | 100 MB | Also HEIC, AVIF, MKV, M4V, OGG and FLAC |
| Studio upload | 2 GB | Same as an MCP upload ticket |
| Base64 JSON body | 3 MiB decoded | Small generated assets |
HEIC photos are stored as JPEG. HEVC, ProRes, MKV and other videos that browsers cannot play get a playable preview copy in the background (preview on the media record: processing, ready or failed); renders always use the original file. hasAudio reports whether an inspected video or audio file has an audio stream.
Uploaded, imported and generated media counts against the plan's storage: Free 250 MB, Hobby 10 GB, Pro 75 GB, Business 500 GB. Project sources and render outputs do not count. GET /api/v2/usage returns storageBytes and storageLimitBytes. An upload above the allowance is rejected with 402 and code: STORAGE_FULL.
Media in the workspace library stays until you delete it. Template media that the published template no longer uses, and project media removed from its project, is deleted after a 7-day grace period.
When a plan or trial ends and the account stores more than Free allows, uploads and new AI media are paused (402, code: STORAGE_LOCKED) and GET /api/v2/usage returns storageLock.deleteAt. On that date, 30 days later, all projects, templates and media of the workspace are deleted. Choosing a plan, or reducing media to 250 MB, cancels the deletion immediately.
Supported public kinds
Public media records use image, video, audio, font or lottie (a Lottie animation stored as JSON). The live upload media operation remains authoritative for request fields and errors. URL import accepts a narrower allowlist than a direct upload and always pins a safe copy.
Inspection result
Inspection can report format, byte size, dimensions, aspect ratio, frame rate, duration, alpha, video codec and audio stream information. Missing metadata stays absent rather than being guessed. Warnings describe a usable file that still deserves attention.
Delete safely
Delete only unused media. A project or template must keep its stable media reference resolvable for preview and rendering. If the API rejects a deletion because the asset is still owned by active work, remove or replace those references first.