Creating Media Entries - Content Management
Creating Media Entries
media.add -- Create Entry Metadata
POST /api_v3/service/media/action/add
| Parameter | Type | Description |
|---|---|---|
entry[objectType] | string | KalturaMediaEntry |
entry[mediaType] | int | 1=Video, 2=Image, 5=Audio |
entry[name] | string | Display name |
entry[description] | string | Description (optional) |
entry[tags] | string | Comma-separated tags (optional) |
entry[referenceId] | string | External reference ID for cross-system linking (optional) |
entry[conversionProfileId] | int | Override default transcoding profile (optional) |
Response: KalturaMediaEntry with id, status (7 = NO_CONTENT until file attached)
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/add" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entry[objectType]=KalturaMediaEntry" \
-d "entry[mediaType]=1" \
-d "entry[name]=My Uploaded Video" \
-d "entry[description]=Uploaded via API" \
-d "entry[tags]=api,upload,demo"
media.addContent -- Attach Upload Token to Entry
POST /api_v3/service/media/action/addContent
| Parameter | Type | Description |
|---|---|---|
entryId | string | The entry ID from media.add |
resource[objectType] | string | Resource type (see table below) |
resource[token] | string | Upload token ID (for KalturaUploadedFileTokenResource) |
Content resource types: The resource parameter accepts any of these types:
| Resource Type | Description | Use Case |
|---|---|---|
KalturaUploadedFileTokenResource | Attach content from an upload token | Standard upload workflow (most common) |
KalturaUrlResource | Import from HTTP/HTTPS/FTP URL | Remote file import |
KalturaEntryResource | Copy content from another entry's flavor | Entry content duplication |
KalturaAssetResource | Copy from a specific flavor asset by ID | Flavor-level content copy |
KalturaOperationResource | Clip, trim, or apply effects to source content | Clipping, concatenation, effects |
KalturaAssetsParamsResourceContainers | Multi-flavor ingest (multiple renditions at once) | Pre-transcoded multi-bitrate content |
KalturaRemoteStorageResource | Register content on configured remote storage | External CDN/S3 content |
KalturaSshUrlResource | Import via SSH/SFTP with key authentication | Secure server file transfer |
KalturaDropFolderFileResource | Reference a file from a configured drop folder | Drop folder integration |
KalturaRemoteStorageResources | Register content on multiple storage profiles | Multi-CDN/multi-region content |
KalturaStringResource | Inline string content (text, XML, JSON) | Caption content, data entries |
KalturaUploadedFileResource | Direct multipart file upload (no token) | Simple single-request upload |
Two additional types exist for internal/system use only (KalturaServerFileResource, KalturaFileSyncResource) and are not available to customer accounts.
Triggers transcoding. Entry status changes from NO_CONTENT (7) to IMPORT (0) or PENDING (4).
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaUploadedFileTokenResource" \
-d "resource[token]=$UPLOAD_TOKEN_ID"
media.updateContent -- Replace an Entry's Source File
POST /api_v3/service/media/action/updateContent
| Parameter | Type | Description |
|---|---|---|
entryId | string | Entry ID to update |
resource[objectType] | string | Resource type (same options as addContent) |
resource[token] | string | Upload token ID |
conversionProfileId | int | Override transcoding profile (optional) |
Replaces the source file while preserving the entry ID, metadata, embed codes, and analytics. The entry enters a "pending replacement" state until transcoding completes. Uses locking to prevent concurrent replacements.
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/updateContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaUploadedFileTokenResource" \
-d "resource[token]=$UPLOAD_TOKEN_ID"
Business scenario — version management: A training team records lecture updates. They replace the video file on the existing entry so all existing playlists, embed codes, and analytics continue working with the new version.
media.approveReplace / media.cancelReplace
When content replacement is configured to require approval:
# Approve pending replacement
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/approveReplace" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID"
# Cancel pending replacement
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/cancelReplace" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID"
Import from URL (KalturaUrlResource)
Use media.add + media.addContent with KalturaUrlResource to import content from a remote URL. Kaltura fetches the file server-side via an async import job. Entry transitions from NO_CONTENT (7) → IMPORT (0) → READY (2).
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaUrlResource |
resource[url] | string | Yes | Direct file URL (HTTP, HTTPS, or FTP) |
resource[urlHeaders] | array | No | Custom HTTP headers for the download request (e.g., auth tokens) |
resource[forceAsyncDownload] | bool | No | Force async import job |
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaUrlResource" \
-d "resource[url]=https://example.com/sample_video.mp4"
With custom headers (e.g., for authenticated sources):
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaUrlResource" \
-d "resource[url]=https://storage.example.com/assets/video.mp4" \
-d "resource[urlHeaders][0]=Authorization: Bearer YOUR_TOKEN"
The URL must point to a direct downloadable file. Streaming manifests (HLS/DASH), redirect URLs (playManifest), and HTML pages cause import failures. Poll media.get until status reaches 2 (READY).
Business scenario — content migration: A media company migrating from another platform exports a CSV of asset URLs. A script iterates through the CSV, creating entries and attaching URL resources for each, then polls until entries reach READY status.
Copy from Existing Entry (KalturaEntryResource)
Use media.add + media.addContent with KalturaEntryResource to create a new entry by copying content from an existing one. The new entry gets its own transcoding run.
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/add" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entry[objectType]=KalturaMediaEntry" \
-d "entry[name]=Copy of Original"
Then attach the source entry's content:
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaEntryResource" \
-d "resource[entryId]=$SOURCE_ENTRY_ID" \
-d "resource[flavorParamsId]=0"
Set resource[flavorParamsId]=0 to copy the original source flavor. Specify a different flavor params ID to copy a specific rendition only.
Business scenario — multi-tenant content: A SaaS platform distributes the same training video to multiple customer accounts, each needing independent analytics and access control.
Copy from Specific Flavor Asset (KalturaAssetResource)
Use media.addContent with KalturaAssetResource to create a new entry from a specific transcoded rendition of an existing entry. Unlike KalturaEntryResource (which references by entry ID + flavor params), this references a flavor asset directly by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaAssetResource |
resource[assetId] | string | Yes | The flavor asset ID to copy from |
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaAssetResource" \
-d "resource[assetId]=$FLAVOR_ASSET_ID"
Business scenario — derivative content: A video platform extracts the audio-only rendition from a lecture recording to create a podcast entry.
Import via SSH/SFTP (KalturaSshUrlResource)
Use KalturaSshUrlResource to import files from SSH/SFTP servers with key authentication.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaSshUrlResource |
resource[url] | string | Yes | SFTP URL (e.g., sftp://host/path/file.mp4) |
resource[privateKey] | string | No | SSH private key content |
resource[publicKey] | string | No | SSH public key content |
resource[keyPassphrase] | string | No | Passphrase for the SSH key |
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaSshUrlResource" \
-d "resource[url]=sftp://media-server.example.com/incoming/video.mp4" \
-d "resource[privateKey]=$SSH_PRIVATE_KEY" \
-d "resource[publicKey]=$SSH_PUBLIC_KEY"
Business scenario — broadcast ingest: A television network's production workflow deposits finished segments on an SFTP server. An automated pipeline picks them up via KalturaSshUrlResource for publishing.
Remote Storage (KalturaRemoteStorageResource)
Use KalturaRemoteStorageResource to register content that lives on a configured remote storage profile (e.g., your own S3 bucket or CDN) without downloading it into Kaltura storage. The file stays in place — Kaltura creates a reference to serve it from its current location.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaRemoteStorageResource |
resource[url] | string | Yes | Path/URL on the remote storage |
resource[storageProfileId] | int | Yes | ID of the configured storage profile |
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaRemoteStorageResource" \
-d "resource[url]=/videos/2024/keynote_1080p.mp4" \
-d "resource[storageProfileId]=$STORAGE_PROFILE_ID"
Requires a storage profile configured on your account (one-time setup by your Kaltura account team). For registering the same content on multiple storage profiles simultaneously, use KalturaRemoteStorageResources (plural) with an array of resources.
Business scenario — hybrid storage: An enterprise keeps original source files in their own S3 bucket for compliance. They register these with Kaltura for playback and metadata management without moving the files.
Drop Folder Files (KalturaDropFolderFileResource)
Use KalturaDropFolderFileResource to reference a file that arrived through a configured drop folder (FTP, SFTP, S3, or local directory watched by Kaltura).
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaDropFolderFileResource |
resource[dropFolderFileId] | int | Yes | ID of the drop folder file object |
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaDropFolderFileResource" \
-d "resource[dropFolderFileId]=$DROP_FOLDER_FILE_ID"
Requires the Drop Folder plugin enabled and a configured drop folder on your account. Files deposited in the drop folder are detected automatically; use this resource type when you need to manually associate a drop folder file with an entry.
Inline String Content (KalturaStringResource)
Use KalturaStringResource to create entries from inline text content. Commonly used for data entries, inline caption content, or metadata files.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource[objectType] | string | Yes | KalturaStringResource |
resource[content] | string | Yes | The text content to store |
curl -X POST "$KALTURA_SERVICE_URL/service/data/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$DATA_ENTRY_ID" \
-d "resource[objectType]=KalturaStringResource" \
-d "resource[content]={\"config\": \"value\", \"version\": 2}"
Also used with captionAsset.setContent to set caption text directly:
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/setContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "id=$CAPTION_ASSET_ID" \
-d "resource[objectType]=KalturaStringResource" \
-d "resource[content]=WEBVTT%0A%0A00:00:00.000 --> 00:00:05.000%0AHello world"
Direct File Upload (KalturaUploadedFileResource)
Use KalturaUploadedFileResource for a single-request upload where the file is sent as multipart form data directly with the addContent call. Simpler than the upload token flow but limited by server upload size limits.
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-F "ks=$KALTURA_KS" \
-F "format=1" \
-F "entryId=$KALTURA_ENTRY_ID" \
-F "resource[objectType]=KalturaUploadedFileResource" \
-F "resource[fileData]=@/path/to/video.mp4"
For files larger than 100 MB, use the upload token workflow (KalturaUploadedFileTokenResource) with chunked upload for resumability.
Clipping, Effects, and Composition (KalturaOperationResource)
Use KalturaOperationResource to create entries by extracting a clip (time segment) from existing content. This resource type also supports fade effects, overlays, background replacement, and caption burn-in.
For a quick clip with offset and duration:
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaOperationResource" \
-d "resource[resource][objectType]=KalturaEntryResource" \
-d "resource[resource][entryId]=$SOURCE_ENTRY_ID" \
-d "resource[resource][flavorParamsId]=0" \
-d "resource[operationAttributes][0][objectType]=KalturaClipAttributes" \
-d "resource[operationAttributes][0][offset]=60000" \
-d "resource[operationAttributes][0][duration]=30000"
For comprehensive documentation of all editing operations — trim, multi-clip concat, overlays, chroma-key background replacement, caption burn-in, effects, dimension control, and audio mixing — see the Video Editing API.
Multi-Clip Concatenation (KalturaOperationResources)
Use KalturaOperationResources (plural) to concatenate segments from multiple source entries into a single output. For full documentation including dimension normalization, chapter naming, and advanced composition, see the Video Editing API.
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaOperationResources" \
-d "resource[resources][0][objectType]=KalturaOperationResource" \
-d "resource[resources][0][resource][objectType]=KalturaEntryResource" \
-d "resource[resources][0][resource][entryId]=$SOURCE_ENTRY_1" \
-d "resource[resources][0][resource][flavorParamsId]=0" \
-d "resource[resources][0][operationAttributes][0][objectType]=KalturaClipAttributes" \
-d "resource[resources][0][operationAttributes][0][offset]=0" \
-d "resource[resources][0][operationAttributes][0][duration]=10000" \
-d "resource[resources][1][objectType]=KalturaOperationResource" \
-d "resource[resources][1][resource][objectType]=KalturaEntryResource" \
-d "resource[resources][1][resource][entryId]=$SOURCE_ENTRY_2" \
-d "resource[resources][1][resource][flavorParamsId]=0" \
-d "resource[resources][1][operationAttributes][0][objectType]=KalturaClipAttributes" \
-d "resource[resources][1][operationAttributes][0][offset]=0" \
-d "resource[resources][1][operationAttributes][0][duration]=15000"
Multi-Flavor Ingest (KalturaAssetsParamsResourceContainers)
Use KalturaAssetsParamsResourceContainers to ingest multiple pre-transcoded renditions in a single addContent call. Each rendition is mapped to a specific flavor params ID.
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
-d "ks=$KALTURA_KS" \
-d "format=1" \
-d "entryId=$KALTURA_ENTRY_ID" \
-d "resource[objectType]=KalturaAssetsParamsResourceContainers" \
-d "resource[resources][0][objectType]=KalturaAssetParamsResourceContainer" \
-d "resource[resources][0][assetParamsId]=0" \
-d "resource[resources][0][resource][objectType]=KalturaUrlResource" \
-d "resource[resources][0][resource][url]=https://example.com/source_original.mp4" \
-d "resource[resources][1][objectType]=KalturaAssetParamsResourceContainer" \
-d "resource[resources][1][assetParamsId]=$FLAVOR_PARAMS_720P" \
-d "resource[resources][1][resource][objectType]=KalturaUrlResource" \
-d "resource[resources][1][resource][url]=https://example.com/video_720p.mp4" \
-d "resource[resources][2][objectType]=KalturaAssetParamsResourceContainer" \
-d "resource[resources][2][assetParamsId]=$FLAVOR_PARAMS_1080P" \
-d "resource[resources][2][resource][objectType]=KalturaUrlResource" \
-d "resource[resources][2][resource][url]=https://example.com/video_1080p.mp4"
Each KalturaAssetParamsResourceContainer maps:
assetParamsId— the target flavor params ID (use0for original source, or specific flavor params IDs from your conversion profile)resource— any content resource type (KalturaUrlResource,KalturaUploadedFileTokenResource, etc.)
Business scenario — broadcast workflow: A broadcaster already has renditions at multiple bitrates from their production pipeline. They ingest all renditions at once, skipping re-transcoding and reducing time-to-publish.
Entry Statuses
| Value | Name | Description |
|---|---|---|
| -2 | ERROR_IMPORTING | Import failed |
| -1 | ERROR_CONVERTING | Transcoding failed |
| 0 | IMPORT | File being fetched/imported |
| 1 | PRECONVERT | Preparing for transcoding |
| 2 | READY | Fully processed, playable |
| 3 | DELETED | Entry deleted |
| 4 | PENDING | Pending processing |
| 5 | MODERATE | Awaiting moderation |
| 6 | BLOCKED | Blocked by admin |
| 7 | NO_CONTENT | Entry created, no file attached |
| virusScan.Infected | INFECTED | File failed virus scan (requires virusScan plugin) |
| virusScan.ScanFailure | SCAN_FAILURE | Virus scan could not complete |
KalturaEntryStatus is a string enum. Core values are numeric strings ("-2" through "7"), and the virusScan plugin contributes dot-notation values. In practice, passing integer 2 or string "2" both work for core statuses in filter parameters. Live stream media types (201-204: LIVE_STREAM_FLASH, LIVE_STREAM_WINDOWS_MEDIA, LIVE_STREAM_REAL_MEDIA, LIVE_STREAM_QUICKTIME) are created via the liveStream service — they use KalturaMediaType, not entry status.
Flavor Asset Statuses
When polling flavor assets during transcoding (flavorAsset.list with entryIdEqual):
| Value | Name | Description |
|---|---|---|
| -1 | ERROR | Transcoding failed for this flavor |
| 0 | QUEUED | Waiting in transcoding queue |
| 1 | CONVERTING | Transcoding in progress |
| 2 | READY | Transcoded and playable |
| 3 | DELETED | Flavor deleted |
| 4 | NOT_APPLICABLE | Flavor params exist but don't apply to this entry |
| 5 | TEMP | Temporary intermediate flavor |
| 6 | WAIT_FOR_CONVERT | Waiting for a dependency flavor to finish |
| 7 | IMPORTING | Source file being imported |
| 8 | VALIDATING | File validation in progress |
| 9 | EXPORTING | Being exported to external storage |
Entry Moderation Statuses
When content moderation is enabled on the account, entries have a moderationStatus field:
| Value | Name | Description |
|---|---|---|
| 1 | PENDING_MODERATION | Awaiting moderator review |
| 2 | APPROVED | Approved for publishing |
| 3 | REJECTED | Rejected by moderator |
| 4 | DELETED | Deleted |
| 5 | FLAGGED_FOR_REVIEW | Flagged by user for review |
| 6 | AUTO_APPROVED | Automatically approved by rules |
For user flagging, moderator approve/reject, AI moderation via REACH, and category-level content gating, see the Moderation API Guide.