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/jsonURIListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_shape_read

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:
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/jsonURIListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_shape_write

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:
Produces:
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:

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/jsonEssenceVersionListDocument 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/jsonEssenceVersionDocument 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:
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:
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:
Role:

_item_shape_read

Shape metadata

New in version 4.0.

Please refer to Key-value metadata.

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:
 
Produces:
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/jsonURIListDocument
  • 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/jsonURIListDocument 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