Shapes

Manage shapes for an item.

Item shapes

List all shapes

GET /item/(id)/shape

Returns all existing shapes for a specified item.

Query Parameters:
  • version (string) –
    • essence-version-id - Return shapes for a specified version.
    • all - Return shapes for all versions.
    • latest (default) - Return shapes for the latest version.
    • latest-per-shapetag - Return shapes with the highest essence version number per shape tag.
  • tag (string) – Comma-separated list. Only return shapes with these tags.
  • url (boolean) –
    • true - Return list of URLs.
    • false (default) - Return list of ids.
  • placeholder (string) –
    • true - Only return placeholder shapes.
    • false (default) - Only return non-placeholder shapes.
    • all - Return all shapes.
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

Retrieve a shape

GET /item/(id)/shape/(shape-id)

Returns a shape for a specified item.

Query Parameters:
  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.
  • storageType (string) – Only return URIs for files from storages of this type.
  • methodMetadata (string[]) – metadata used with storage method.
  • scheme (string) – URI scheme to return.
  • transient (boolean) –
    • 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 (boolean) –
    • 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

Retrieve a graphical representation of a shape

GET /item/(id)/shape/(shape-id)/graph

Shows components and tracks in a graphical format.

Produces:
  • image/png
Role:

_item_shape_read

Retrieve a shape as a dot file

GET /item/(id)/shape/(shape-id)/graph/dot

Shows components and tracks in a graphical format in dot format, for further processing.

Produces:
  • text/plain
Role:

_item_shape_read

Retrieve a shape as an IMF CPL

GET /item/(id)/shape/(shape-id)/cpl

Returns component information as CPL.

Produces:
  • application/xml
Role:

_item_shape_read

Delete 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 (boolean) –
    • 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 (boolean) –
    • true - Keep the files belong to this shape.
    • false (default) - Remove the files belong to this shape.
  • updateMetadata (boolean) –
    • true - Remove the item metadata that is generate from this shape
    • false (default) - Keep the item metadata that is generate from this shape
  • notificationMetadata (string[]) –

    Adds custom metadata to the notification.

    Example: notificationMetadata=Reason=Some_Reason. The equals sign of the value has to be URL encoded (%3d)

    New in version 22.1.

Produces:
  • application/xml, application/jsonURIListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_shape_write

Delete all shapes

DELETE /item/(id)/shape/

Removes all shapes, regardless of essence version, for the specified item. This will remove all components and mark files for deletion, unless files are used in other shapes.

To delete all shapes for a specific essence version, see DELETE /item/(id)/shape/version/(version).

Query Parameters:
  • keepFiles (boolean) –
    • true - Keep the files belong to the shapes.
    • false (default) - Remove the files belong to the shapes.
  • notificationMetadata (string[]) –

    Adds custom metadata to the notification.

    Example: notificationMetadata=Reason=Some_Reason. The equals sign of the value has to be URL encoded (%3d)

    New in version 22.1.

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 (string) – A URI to the file that will be imported. Make sure to percent encode the URI. Must be specified unless fileId is specified.
  • fileId (string) – The id of the file that contains the essence. Must be specified unless uri is specified.
  • allowReimport (boolean) –
    • 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 (string) – The tags to assign to the new shape.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
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 (string) – The tags to assign to the new shape.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • filename (string) –

    Deprecated since version 23.3: Use originalFilename instead.

    The filename that will be stored in the originalFilename metadata field. If both filename and originalFilename are provided, originalFilename will be used.

  • originalFilename (string) – The filename that will be stored in the originalFilename metadata field. If both filename and originalFilename are provided, originalFilename will be used.
  • transferPriority (integer) – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers. A transfer with a high priority value is considered more important than a transfer with a low priority value.
  • transferId (string) – An id to assign the transfer to be able to refer to it.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
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.

Changed in version 4.17.2: If the shape document has components that reference files (by id), then these files will be associated with the corresponding component.

Query Parameters:
  • tag (string) – The tags to assign to the new shape.
  • updateItemMetadata (boolean) – If the shape is tagged original and this query parameter is true, the item’s system metadata (e.g. durationSeconds) is updated. Default is false.
Accepts:
Produces:
Role:

_import

Import a shape from an IMF package

POST /item/(id)/shape/imp

Starts a new shape import job using a URI of an IMF asset map

Changed in version 5.3: IMF packages will now be validated using Photon and results saved as metadata on the item. Can be disabled with jobMetadata parameter.

Query Parameters:
  • uri (string) – The URI of the asset map
  • tag (string) – The tags to assign to the new shape.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • removeOldEssenceFiles (boolean) –
    • true - Remove files associated with shapes with same tags and lower essence version.
    • false (default) - Keep the files belong to the shapes.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

The IMF shape import job accepts certain special jobMetadata parameters:

skipImpValidation

If set to true, do not perform Photon IMF package validation.

New in version 5.3.

Creating thumbnails and posters

Thumbnails and posters of a specific shape can be created by starting a thumbnail job.

Start a thumbnail job

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.

Changed in version 5.0: For multi-layer PSD/PSB files, only a thumbnail of all layers flattened will be generated by default.

Query Parameters:
  • createThumbnails (boolean) –
    • 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 (string) – A list of time codes to use for creating posters.
  • thumbnailWidth (integer) – The width of the thumbnails. If thumbnailWidth is specified, thumbnailHeight must also be specified.
  • thumbnailHeight (integer) – The height of the thumbnails. If thumbnailHeight is specified, thumbnailWidth must also be specified.
  • thumbnailPeriod (string) – 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 (integer) – The width of the posters.
  • posterHeight (integer) – The height of the posters.
  • posterFormat (string) –
    • jpeg (default) - Creates posters in JPEG format.
    • png - Creates posters in PNG format.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • tag (string) – Include additional video settings from this transcode preset. Resolution settings in the tag are overridden by query parameters thumbnailHeight and thumbnailWidth.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
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.

List all essence versions

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 an 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 (string) – A URI to the file that will be imported. Make sure to percent encode the URI. Must be specified unless fileId is specified.
  • fileId (string) – The id of the file that contains the essence. Must be specified unless uri is specified.
  • allowReimport (boolean) –
    • 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.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • frame-rate (string) –

    New in version 22.1.

    The frame rate of the image sequence.

  • tag (string) – The tags to assign to the new shape.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Import an 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 (string) – The tags to assign to the new shape.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • filename (string) –

    Deprecated since version 23.3: Use originalFilename instead.

    The filename that will be stored in the originalFilename metadata field. If both filename and originalFilename are provided, originalFilename will be used.

  • originalFilename (string) – The filename that will be stored in the originalFilename metadata field. If both filename and originalFilename are provided, originalFilename will be used.
  • transferPriority (integer) – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers. A transfer with a high priority value is considered more important than a transfer with a low priority value.
  • transferId (string) – An id to assign the transfer to be able to refer to it.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
Accepts:
  • application/octet-stream – The raw essence data.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Retrieve an essence version

GET /item/(id)/shape/version/(version)

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

Delete an essence version

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

Copy an essence version of a shape to a new version

POST /item/(id)/shape/(shape-id)/version

Copies the specified shape to a new shape, with the new latest essence version number.

Produces:
  • application/xml, application/jsonShapeDocument containing the new shape.
Role:

_item_shape_write

Copy an essence version of a shape to a specific version

PUT /item/(id)/shape/(shape-id)/version/(new-version)

Copies the specified shape to a new shape, with the given essence version number.

Produces:
  • application/xml, application/jsonShapeDocument containing the new shape.
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 (string) – Comma-separated shape tags to be added to the shape.
  • container (integer) – The number of container components
  • audio (integer) – The number of audio components
  • video (integer) – The number of video components
  • binary (integer) – The number of binary components
  • subtitle (integer) – The number of subtitle components
  • frameDuration (string) – duration for each image in the sequence.
Accepts:
Produces:
  • text/plain – The id of the new shape.
Role:

_import

Update a placeholder shape

PUT /item/(id)/shape/(shape-id)/placeholder

Updates the expected number of container, video, audio and binary components for a specific placeholder shape.

Query Parameters:
  • tag (string) – Comma-separated shape tags to be added to the shape.
  • container (integer) – The number of container components
  • audio (integer) – The number of audio components
  • video (integer) – The number of video components
  • binary (integer) – The number of binary components
  • subtitle (integer) – The number of subtitle components
Accepts:
Role:

_import

Shape files

List all files for a shape

GET /item/(id)/shape/(shape-id)/file

Returns all files that are associated with the specified shape.

Query Parameters:
  • includeItem (boolean) –
    • true - Return associated items, shapes, and components.
    • false (default) - Do not return any information about associated items, shapes, and components.
  • closedFiles (boolean) –
    • true (default) - Return only files that are closed.
    • false - Return all files.
  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.
  • storageType (string) – Only return URIs for files from storages of this type.
  • methodMetadata (string[]) – metadata used with storage method.
  • scheme (string) – URI scheme to return.
Produces:
Role:

_item_shape_read

Move/copy all files in a shape to another storage

POST /item/(item-id)/shape/(shape-id)/storage/(target-storage-id)

New in version 23.2.

Create a move or copy job to transfer all file components within a shape to a storage

Query Parameters:
  • move (boolean) –
    • true - Delete the original file when the copy has finished.
    • false - Just copy the file, and leave the original.
  • useOriginalFilename (boolean) – If set to true, the file will keep its original filename if available. Default is false.
  • timeRequirement (integer) – Number of seconds the target file is required to exist before being moved due to storage rules etc.
  • limitRate (integer) – Throttle the rate at which the transfer takes place (bytes/second).
  • sourceStorageId (string) – Identifier of storage where shape files will be copied(moved) to the target storage. Default is all. If default shape files from all storages will be copied(moved) to the target storage.
  • subPath (string) – The destination path where shape files will be copied(moved) to.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
Role:

_file_write

Archive and restore a shape

Archive a shape

POST /item/(item-id)/shape/(shape-id)/archive

Starts a job for archiving the shape’s files to the given ARCHIVE storage.

Query Parameters:
  • storageId (string) –

    Identifier of storage where essence file is to be stored.

    This storage must be of type ARCHIVE.

  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
Role:

_item_shape_read

Role:

_job_write

Restore a shape

POST /item/(item-id)/shape/(shape-id)/restore

Starts a job for restoring the shape’s files from archive, to the given storage.

Query Parameters:
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
Role:

_item_shape_read

Role:

_job_write

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 (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
  • extractCc (string) –

    Extract closed captions as metadata. Allowed values: true and mcc

    New in version 22.1.

    Extract WebVTT subtitle as metadata. Allowed value: webvtt

    New in version 22.4.

  • ccFromVideo (boolean) –

    New in version 22.1.

    • true - Extract closed captions from video tracks as well as data tracks.
    • false (default) - Extract closed captions from data tracks only.
Produces:
Role:

_item_shape_write

Tags of a shape

List all tags for a shape

GET /item/(item-id)/shape/(shape-id)/tag/

Retrieves all shape tags associated with a certain shape.

Query Parameters:
  • url (boolean) –
    • 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 to a shape

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 from a shape

DELETE /item/(id)/shape/(shape-id)/mime/(mime-type)

Removes a mime type from the shape.

Role:_item_shape_write