KalturaAPI:main
From Kaltura Wiki
Contents |
[edit] Introduction
Kaltura's Application Programming Interfaces (APIs) allow partners to interact with the platform through web-services. API's are based on the REST principles Where each request can be an HTTP POST or GET, and the response is a gziped content (If client specified that gzip is supported).
Each Kaltura API method located at a unique URL:
http://www.kaltura.com/api/methodname where [method name] is the name of the API method.
In order to use the Kaltura API please make sure you are properly prepared for the integration.
General API Inputs and Outputs - Read about it here
API Test Console -A reference implementation can be found at Test Console
[edit] Kaltura Objects
- Entry - An entry is a media entity and it's meta data on the Kaltura servers. It can be an image, a sound clip, a video or a rough-cut (explained below) wrapped with vast information such as dates, titles, tags, ratings and more. The Kaltura extensive API enables its partners to create galleries, lists, playlists and more by calling up various entry-related API calls as well as edit this information on the fly.
- KShow - A KShow (Kaltura Show) is a 'container' of related entries. The main use of a kshow is as the 'higher entity' of a remix and contains all of the images, sound clips, videos and rough-cuts that create one remix. A kshow is also playable by the KDP and when played it redirects to the most recent version of the rough-cut in the kshow (as a rough-cut can be edited and manipulated). Similar to an entry, A Kshow is also wrapped with metadata and has an extensive representation in the Kaltura API. Note a KShow can be used to store entries related to a specific user or topic (regardless of mixes).
- User (Partner User) - Representation of partner's user in Kaltura's DB.
- Widget - A widget represents a KDP which is either bound to a specific media clip (in the case of media embedded in an external site) or a KDP that can show a gallery of media clips which can be selected via flashvars and javascript calls.
- UIConf (Internal) - XML configuration file for various Kaltura components (KDP, KSE, KCW)
- Also see Filter Operators, Entry Filter (Input) and KShow Filter (Input).
[edit] Kaltura Session (KS)
Kaltura servers authenticate calls using a KS (Kaltura session). A Kaltura session is generated using the startsession API call. Each KS includes a partner, sub partner, user id, API secret and optional privileges. The KS is used to call additional API calls and to allow the client side (Flex) components to send authenticated calls to Kaltura servers.
Security note: you should never let your partner secret leave your servers. It is used solely for creating a KS which can be passed to untrusted clients (e.g. browser, flex component). Likewise, an admin KS (created using the startsession and the admin secret) should never reach the browser as well. By letting users access an admin KS they will be able to cause changes not limited to their own media.
The user id passed in all of the Kaltura API calls is the user id on your system (e.g. a numeric id, screen name, email). Whenever a call is made, Kaltura’s system will implicitly create a record for the user on its servers.
[edit] Methods
- Add Entry
- Adds new entry to a roughcut or a kshow. Most basic API based upload.
- Add Download
- Converts the specified entry (roughcut) to a downloadable file using the requested format.
- Add KShow
- Adds new KShow.
- Add User
- Adds a new user.
- Add Widget
- Adds a new widget.
- Append Entry To Roughcut
- Appends existing entry to a roughcut.
- Clone KShow
- Clones an existing KShow including its roughcut. The cloned kshow will be a subject of the original kshow.
- Collect Stats
- Collect statistics about special events from the client.
- Delete Entry
- Deletes an entry.
- Delete KShow
- Deletes a KShow.
- Delete User
- Deletes a user.
- Get All Entries
- Get all entries by entry_id or kshow_id.
- Get Default Widget
- Return a default widget for the partner, if ui_conf_id is not passed the widget will be created using a default UIConf.
- Get Entries
- Get entries by list of ids comma separated.
- Get Entry
- Get entry by id.
- Get KShow
- Get KShow by id.
- Get Last Versions Info
- Get an info about the last versions of a KShow.
- Get Meta Data
- Get the metadata of a roughtcut.
- Get Roughcut
- Same result as "Get Entry" but with allVersionsFormatted field .
- Get Partner
- Get the data of a partner that belongs to an admin given his email, password and partner_id.
- Get UIConf
- Get UIConf by id.
- Get User
- Get user by id.
- Get Widget
- Get widget by id.
- List Entries
- List entries by filter with paging support.
- List KShows
- List kshows by filter with paging support.
- List My Entries
- List entries by filter with paging support for the user initiated the call.
- List My KShows
- List kshows by filter with paging support for the user initiated the call.
- Rank KShow
- Ranks a kshow (rank can be 0-5)
- Register Partner
- Registers a new partner.
- Rollback KShow
- Rollback a kshow to a previous version.
- Search
- Search for media in a specific media source.
- Search Auth Data
- Used to get authentication when searching media at users profile.
- Search Media Info
- Used to get additional info about the media when not possible to get from the main search request.
- Set Metadata
- Set roughcut metadata.
- Start Session
- Starts new session.
- Start Widget Session
- Start new anonymous sessions (This is used in the KDP when viewing a video).
- Update Entries Thumbnails
- Update thumbnails for a list of entries by the specified time offset (in seconds).
- Update Entry
- Update entry data.
- Update Entry Thumbnail
- Update thumbnail for an entry by the specified time offset (in seconds).
- Update Entry Thumbnail JPEG
- Update entry thumbnail using a raw jpeg file, binary image data should be sent in the HTTP body.
- Update KShow
- Update KShow data.
- Update KShow Owner
- Updates the owner (creator) of the kshow.
- Update User
- Update user data.
- Update User ID
- Update partners user id.
- Upload
- Allows upload of media files.
- Upload JPEG
- Allow upload of images filename should be unique per upload session.
[edit] Enumerations
- Response Formats - Depending on the a special parameter called 'format', the result can be sent in various formats.
- Entry Status Enum - Status of entry.
- Entry Type Enum - Type of entry.
- Entry Media Type Enum - Media type of entry.
- List Type Enum - Can be used in a bitwise AND operation when calling Get All Entries.
- Entry Media Source - list of available media providers.
- KShow Status Enum - KShow status.
[edit] Notifications
Sent by the Kaltura servers to a partner system. These notifications enable a partner system to provide its own searching capabilities and caching for Kaltura stored data. The Kaltura servers log required operations and then send notifications asynchronously. The Kaltura servers send notifications using HTTP post requests to a given dispatcher URL on the partner host servers. Read detailed information on our Notifications wiki page and get a list of available notifications.
Also check out our Process a Notification How-To Guide.
[edit] Extra URL Services
These services are actually dynamic urls which return media (images and videos).
To access these services the following format should be used: http://cdn.kaltura.com/p/{partner_id}/sp/{subp_id}/servicename/{params}.
| Service Name | General Description |
|---|---|
| thumbnail | Return the thumbnail (or actual image) of an entry resized and modified as requested. |
| flvclipper | Returns a trimmed video file of an entry. |
| raw | Returns a the raw (original pre-transcoding) version of an entry. |
[edit] API Message Board
Visit our API community forum, ask questions or make suggestions.
