Shapes¶
Item shapes¶
Get list of shapes¶
- GET /item/(id)/shape¶
Returns all existing shapes for a specified item.
Matrix Parameters: - version –
- essence-version-id - Return shapes for a specified version.
- all - Return shapes for all versions.
- latest (default) - Return shapes for the latest version.
Query Parameters: - url –
- true - Return list of URLs.
- false (default) - Return list of ids.
- placeholder –
New in version 4.2.3.
- true - Only return placeholder shapes.
- false (default) - Only return non-placeholder shapes.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – URIListDocument
- text/plain – CRLF-delimited list of ids or URLs
Role: _item_shape_read
- version –
Get shape¶
- GET /item/(id)/shape/(shape-id)¶
Returns a shape for a specified item.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – ShapeDocument
Role: _item_shape_read
Deleting a shape¶
- DELETE /item/(id)/shape/(shape-id)¶
Removes the specified shape. This will remove all components and and mark files for deletion, unless files are used in other shapes.
Query Parameters: - url –
- true - Instead of shape ids, return the full paths of the shapes in the response document.
- false (default) - Only return the ids of the remaining shapes.
- keepFiles –
- true - Keep the files belong to this shape.
- false (default) - Remove the files belong to this shape.
- updateMetadata –
- true - Remove the item metadata that is generate from this shape
- false (default) - Keep the item metadata that is generate from this shape
Produces: - application/xml, application/json – URIListDocument
- text/plain – CRLF-delimited list of ids or URLs
Role: _item_shape_write
- url –
Importing a new shape¶
New shape can be imported in one of two methods. Both methods share a lot of similarities to item imports, using a URI or using the request body. The difference between a shape import and an essence version import is that it does not increment the essence version nor does it perform any transcoding.
Import a shape using a URI or an existing file¶
- POST /item/(id)/shape¶
Starts a new shape import job using either a URI or a file id.
Query Parameters: - uri – A URI to the file that will be imported. See also URI’s, URL’s, and Special Characters. Must be specified unless fileId is specified.
- fileId – The id of the file that contains the essence. Must be specified unless uri is specified.
- tag – The tags to assign to the new shape.
- settings – Pre-configured import settings. See Import settings
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Import a shape using the request body¶
- POST /item/(id)/shape/raw¶
Starts a new shape import job using the data in the request data.
Query Parameters: - tag – The tags to assign to the new shape.
- transferId – An id to assign the transfer to be able to refer to it. Mandatory for chunked and passkey imports.
- transferPriority – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers (optional). A transfer with a high priority value is considered more important than a transfer with a low priority value.
- settings – Pre-configured import settings. See Import settings
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Status Codes: - 400 –
If the amount of data received does not match the given Content-Length header.
New in version 4.2.3.
Accepts: - application/octet-stream – The raw essence data.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Create a shape using shape technical information¶
- POST /item/(id)/shape/create¶
Creates a new shape using the supplied information.
Query Parameters: - tag – The tags to assign to the new shape.
- updateItemMetadata – If the shape is tagged original and this query parameter is true, the item’s system metadata (e.g. durationSeconds) is updated.
Accepts: - application/xml, application/json – ShapeDocument
Produces: - application/xml, application/json – ShapeDocument
Role: _import
Creating thumbnails and posters¶
Thumbnails and posters of a specific shape can be created by starting a thumbnail job.
Start a thumbnail job¶
New in version 4.2.3.
- POST /item/(item-id)/shape/(shape-id)/thumbnail¶
Creates a new thumbnail job with the specified parameters. Note that a job cannot both create thumbnails at specified intervals and posters. Creating thumbnails according to transcoder rules and creating posters is however allowed.
Query Parameters: - createThumbnails –
- true - Creates thumbnails according to default transcoder rules.
- t1, ... - Thumbnails will be created on the specified, comma-separated, Time codes.
- false (default) - No thumbnails will be created.
- createPosters – An optional list of Time codes to use for creating posters.
- thumbnailWidth – An optional integer specifying the width of the thumbnails.
- thumbnailHeight – An optional integer specifying the width of the thumbnails.
- thumbnailPeriod – An optional timecode string specifying the interval of the thumbnails. It should be a decimal integer when working with multi-page images/PDFs, meaning every N page(s).
- posterWidth – An optional integer specifying the width of the posters.
- posterHeight – An optional integer specifying the width of the posters.
- posterFormat –
- jpeg (default) - Creates posters in JPEG format.
- png - Creates posters in PNG format.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
- createThumbnails –
Essence versions¶
New versions of essence can be imported in one of two methods. Both methods share a lot of similarities to item imports, using a URI or using the request body.
Get all essence versions for an item¶
- GET /item/(id)/shape/version¶
Returns a list containing URLs to all essence versions of the item.
Produces: - application/xml, application/json – EssenceVersionListDocument containing information to all essence versions of the item.
Role: _item_shape_read
Import essence version using a URI or an existing file¶
- POST /item/(id)/shape/essence¶
Starts a new essence import job using either a URI or a file id.
Query Parameters: - uri – A URI to the file that will be imported. See also URI’s, URL’s, and Special Characters. Must be specified unless fileId is specified.
- fileId – The id of the file that contains the essence. Must be specified unless uri is specified.
- tag – The tags to assign to the new shape.
- settings – Pre-configured import settings. See Import settings
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Import essence version using the request body¶
- POST /item/(id)/shape/essence/raw¶
Starts a new essence import job using the data in the request data.
Query Parameters: - tag – The tags to assign to the new shape.
- transferId – An id to assign the transfer to be able to refer to it. Mandatory for chunked and passkey imports.
- transferPriority – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers (optional). A transfer with a high priority value is considered more important than a transfer with a low priority value.
- settings – Pre-configured import settings. See Import settings
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Status Codes: - 400 –
If the amount of data received does not match the given Content-Length header.
New in version 4.2.3.
Accepts: - application/octet-stream – The raw essence data.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Get a particular essence versions for an item¶
- GET /item/(id)/shape/version/(version-number)¶
Returns a list of shapes from the specified version.
Produces: - application/xml, application/json – EssenceVersionDocument containing all the shapes with the specified version.
Role: _item_shape_read
Deleting an essence version of an item¶
- DELETE /item/(id)/shape/version/(version)¶
Deletes all shapes associated with the specified version. Thumbnails connected to the version will also be deleted.
Role: _item_shape_write
Create/delete shapes¶
Create shape¶
- POST /item/(id)/shape¶
Matrix Parameters: - version –
- essence-version-id - Version to use.
- latest (default) - Use latest version of item.
Query Parameters: - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Accepts: - application/xml, application/json – ShapeDocument
Produces: - application/xml, application/json – JobDocument
- text/plain – Job URL
Role: _item_shape_write
- version –
Semantics¶
Creates a new shape for the specified item. Actually, this function will create a new job that will
- create a new shape
- allocate files on adequate storages, or allocate files on storages given as input
- create transfer/transcode jobs
Only source files from the specified version is used to create the new shape. The new shape will have the same essence version as the original essence.
Update shape with new essence¶
- POST /item/(id)/shape/(shape-id)/update¶
Generates a new shape.
Matrix Parameters: - version –
- essence-version-id - Version to use.
- latest (default) - Use latest version of item.
Produces: - application/xml, application/json – ShapeDocument
- text/plain – Shape URL
Role: _item_shape_write
- version –
Semantics¶
Generates a new shape given structure for the specified shape, and the essence from another essence version. The new shape will have a new shape id, and the essence version will be the one specified.
Modify shapes¶
- PUT /item/(id)/shape/(shape-id)/placeholder¶
Query Parameters: - tag – Optional comma separated shape tags to be added to the shape.
- container – Optional integer, the number of container components
- audio – Optional integer, the number of audio components
- video – Optional integer, the number of video components
Accepts: - application/xml, application/json – SimpleMetadataDocument
Role: _import
Semantics¶
Creates a new shape for the specified item. Actually, this function will create a new job that will
- create a new shape
- allocate files on adequate storages, or allocate files on storages given as input
- create transfer/transcode jobs
Only source files from the specified version is used to create the new shape. The new shape will have the same essence version as the original essence.
Shape files¶
Get files for shape¶
- GET /item/(id)/shape/(shape-id)/file¶
Returns all files that are associated with the specified shape.
Produces: - application/xml, application/json – ComponentListDocument
Role: _item_shape_read
Updating an existing shape¶
If the shape deduction on import for some reason gave an incorrect result, it is possible to re-run the shape deduction using this command.
Re-run a shape deduction on an existing shape¶
- POST /item/(item-id)/shape/(shape-id)/update¶
Starts a new shape deduction job for the specified shape.
Query Parameters: - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is MEDIUM .
- jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
Role: _item_shape_write
Tags of a shape¶
Get a list of tags associated with a shape¶
- GET /item/(item-id)/shape/(shape-id)/tag/¶
Retrieves all shape tags associated with a certain shape.
Produces: - application/xml, application/json – URIListDocument
- text/plain – A list of the tags.
Role: _shape_tag_read
Add a tag to a shape¶
- PUT /item/(item-id)/shape/(shape-id)/tag/(tag-name)¶
Adds shape tag with the given name to the specified shape. If the shape already has that tag, this operation does nothing.
Status Codes: - 200 OK – Tag added successfully.
- 404 Not found – No tag with that name exists.
Role: _shape_tag_write
Remove a tag from a shape¶
- DELETE item/(item-id)/shape/(shape-id)/tag/(tag-name)¶
Removes a tag with the given name from the specified shape.
Status Codes: - 200 OK – Tag added successfully.
- 404 Not found – No tag with that name exists within the shape.
Role: _shape_tag_write
Shape mime types¶
List all mime types for a shape¶
- GET /item/(id)/shape/(shape-id)/mime/¶
Lists all mime types that are set on the shape. These can also be seen the ShapeDocument of the shape.
Produces: - application/xml, application/json – URIListDocument containing all the mime types of the shape.
Role: _item_shape_read
Add a mime type¶
- PUT /item/(id)/shape/(shape-id)/mime/(mime-type)¶
Adds a new mime type to the shape. This operation does nothing if the shape already has the mime-type.
Role: _item_shape_write
Remove a mime type¶
- DELETE /item/(id)/shape/(shape-id)/mime/(mime-type)¶
Removes a mime type from the shape.
Role: _item_shape_write