Shapes¶
Item shapes¶
Get list of shapes¶
- GET /item/(id)/shape¶
Returns all existing shapes for a specified item.
Query 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.
- tag – Optional comma-separated list. Only return shapes with these tags.
- url –
- true - Return list of URLs.
- false (default) - Return list of ids.
- placeholder –
- true - Only return placeholder shapes.
- false (default) -
Only return non-placeholder shapes.
New in version 4.2.3.
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.
Query Parameters: - methodType – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType. see Storage methods.
- storageType – Only return URIs for files from storages of this type. See Storages.
- methodMetadata – Optional metadata used with storage method. See Storages.
- scheme – URI scheme to return.
- transient –
- true - Return the shape by inspecting the file on disk. Use with growing files to get an as up-to-date shape as possible.
- false (default) - Return the shape that was last read from the file.
- includePlaceholder –
- true - Include expected but not yet imported components in the shape.
- false (default) - Do not include placeholder components.
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.
- allowReimport –
- true - Import the file to this shape even if the file is already importing or is already part of another item.
- false (default) Reject the request if the file with the given id has already been imported or is currently importing.
- tag – The tags to assign to the new shape.
- 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.
- filename – The filename to be stored as original filename. Optional.
- 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.
- 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 height 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 height of the posters.
- posterFormat –
- jpeg (default) - Creates posters in JPEG format.
- png - Creates posters in PNG format.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- tag – Include additional video settings from this transcode preset.
- 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.
- allowReimport –
- true - Import the file to this shape even if the file is already importing or is already part of another item.
- false (default) Reject the request if the file with the given id has already been imported or is currently importing.
- tag – The tags to assign to the new shape.
- 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.
- storageId – Optional identifier of storage where essence file is to be stored.
- filename – The filename to be stored as original filename. Optional.
- 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.
- 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
Placeholder shapes¶
Create a placeholder shape¶
- POST /item/(id)/shape/placeholder¶
Creates an new placeholder shape for a specific item.
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
- frameDuration – Optional Time durations for each image in the sequence (optional).
Accepts: - application/xml, application/json – SimpleMetadataDocument
Produces: - text/plain – The id of the new shape.
Role: _import
Modify a placeholder shape¶
- PUT /item/(id)/shape/(shape-id)/placeholder¶
Updates the expected number of container, video and audio components for a specific placeholder shape.
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
Shape files¶
Get files for shape¶
- GET /item/(id)/shape/(shape-id)/file¶
Returns all files that are associated with the specified shape.
Matrix Parameters: - includeItem –
- true - Return associated items, shapes, and components.
- false (default) - Do not return any information about associated items, shapes, and components.
Query Parameters: - closedFiles –
- true (default) - Return only files that are closed.
- false - Return all files.
- methodType – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType. see Storage methods.
- storageType – Only return URIs for files from storages of this type. See Storages.
- methodMetadata – Optional metadata used with storage method. See Storages.
- scheme – URI scheme to return.
Produces: - application/xml, application/json – FileListDocument
Role: _item_shape_read
- includeItem –
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.
Query Parameters: - url –
- true - Return list of URLs.
- false (default) - Return list of ids.
Produces: - application/xml, application/json – URIListDocument
- text/plain – A list of the tags.
Role: _shape_tag_read
- url –
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.
- text/plain – CRLF-delimited list of mime types
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