Imports

Trigger imports of files, sidecar files and IMF packages.

Importing an item

An item can be imported in two ways, either through supplying a URI or sending the data in the request body.

There is also a third automatic way, using Automatic import.

Import using a URI

POST /import

Starts a job that imports the file, located at the given URI, and creates an item. Note that thumbnails and poster frames are only generated if a transcode takes place.

Query Parameters:
  • uri (string) – Required. A URI to the file that will be imported. Make sure to percent encode the URI.
  • URL (string) – A URL to the file that will be imported. (Deprecated since 4.2.)
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • no-mediacheck (boolean) –

    Only for for import of mpeg-dash mpd, skip media check to speed up import.

    • true - Will disable media check.
    • false (default) - Normal media check.
  • frame-rate (string) –

    New in version 22.1.

    The frame rate of the image sequence.

  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • growing (boolean) –
    • true - Specifies that the input file is still written to, so enables growing file support.
    • false (default) - No growing file handling of import file.
  • xmpfile (string) – URI to a sidecar XMP metadata file.
  • sidecar (string) – URIs or file ids of any sidecar files to import to the item.
  • settings (string) – Pre-configured import settings.
  • 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.
  • 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.
  • resourceTag (string) –

    New in version 22.4.

    The resource tag criteria used to select transcoders for the job.

    Boolean operators - AND, OR, NOT - are supported.

    Examples: resourceTag=location:stockholm,

    resourceTag=location:stockhom OR location:berlin,

    resourceTag=(location:stockhom OR location:berlin) AND (type:blue OR NOT type:red).

Accepts:
  • application/xml, application/jsonMetadataDocument, initial metadata that is given to the imported item.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Example

POST /import?uri=http://example.com/video.avi HTTP/1.1
Accept: application/xml
Content-type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan end="+INF" start="-INF">
         <field>
            <name>title</name>
            <value>This is an imported item!</value>
         </field>
      </timespan>
</MetadataDocument>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <jobId>VX-80</jobId>
    <status>READY</status>
    <type>PLACEHOLDER_IMPORT</type>
</JobDocument>

Import using the request body

POST /import/raw

Starts a job that reads the raw data from the request body, generates a file, and imports the file.

Query Parameters:
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • 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.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • 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.
  • 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.
  • settings (string) – Pre-configured import settings.
  • ids (string) – Comma-separated list of external ids to assign to the item.
  • 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.
  • resourceTag (string) –

    New in version 22.4.

    The resource tag criteria used to select transcoders for the job.

    Boolean operators - AND, OR, NOT - are supported.

    Examples: resourceTag=location:stockholm,

    resourceTag=location:stockhom OR location:berlin,

    resourceTag=(location:stockhom OR location:berlin) AND (type:blue OR NOT type:red).

  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
Request Headers:
  • index – Offset (in bytes) of the full file for where the first byte of this transfer is located.
  • size – The total size of the full file.
Accepts:
  • application/octet-stream – The raw data.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job, or no content if the transfer is not finished.
Role:

_import

Semantics

There are two modes of operation for this type of import. The most simple is to transfer the entire file and then the header parameters can be ignored. The other is to transfer the file over multiple requests, then the header parameters are required. If the latter mode is used, then the job will not start until the entire file is transferred.

Note that thumbnails and poster frames are only generated if a transcode takes place.

Tip

Managing transfers

Transfers can be managed, see Transfers.

Example: transferring the entire file

POST /import/raw HTTP/1.1
Content-Type: application/octet-stream

<the entire file data>

Example: transferring a file using multiple requests

Assume a file that is 1000 bytes. This file can be sent using three requests, where one request sends data [800, 1000], another sends data [0, 300] and the last request sends data [300, 800].

POST /import/raw?transferId=mytransfer HTTP/1.1
Content-Type: application/octet-stream
size: 1000
index: 800

<200 bytes of file data, starting at byte 800>
POST /import/raw?transferId=mytransfer HTTP/1.1
Content-Type: application/octet-stream
size: 1000
index: 0

<300 bytes of file data, starting at byte 0>
POST /import/raw?transferId=mytransfer HTTP/1.1
Content-Type: application/octet-stream
size: 1000
index: 300

<500 bytes of file data, starting at byte 300>

The last request that finishes will start the job and receive the corresponding job document.

Import using a passkey

POST /import/raw-passkey

Create a job and generates a passkey that can later be used to import an item without being authenticated.

Query Parameters:
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • 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) – Required. An id to assign the transfer to be able to refer to it.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • 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.
  • 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.
  • settings (string) – Pre-configured import settings.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • ids (string) – Comma-separated list of external ids to assign to the item.
  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
  • 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.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
Accepts:
  • application/xml, application/jsonMetadataDocument, initial metadata that is given to the imported item.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Example

POST /import/raw-passkey?transferId=mytransfer HTTP/1.1
Accept: application/xml
Content-type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan end="+INF" start="-INF">
         <field>
            <name>title</name>
            <value>This is an imported item!</value>
         </field>
      </timespan>
</MetadataDocument>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <jobId>VX-102</jobId>
    <status>WAITING</status>
    <type>RAW_IMPORT</type>
    <data>
        <key>passkey</key>
        <value>91df2b2fe74957cc7331d59a59a88cdc14df460dbb4d62c20287399b30092134</value>
    </data>
</JobDocument>

Importing without authentication

Note

Note that this request uses http://server:port/APInoauth/... instead of the usual http://server:port/API/...

POST /APInoauth/import/raw

Imports the item and starts the job.

Query Parameters:
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • 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.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • 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.
  • 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.
  • settings (string) – Pre-configured import settings.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
Accepts:
  • application/octet-stream, multipart/form-data – The raw essence data. If sent as multipart form data, the file should then be sent in the file parameter.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Example

POST /import/raw?transferId=mytransfer&passkey=91df2b2fe74957cc7331d59a59a88cdc14df460dbb4d62c20287399b30092134
Accept: application/xml
Content-type: application/octet-stream

<file data>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <jobId>VX-102</jobId>
    <user>admin</user>
    <started>2010-08-11T09:57:29.575+02:00</started>
    <status>READY</status>
    <type>RAW_IMPORT</type>
    <priority>MEDIUM</priority>
</JobDocument>

Import an IMF package using a URI

POST /import/imp

Starts a job that reads the asset map of an IMP (IMF package), and then imports the IMP. Essence files whose UUID is already managed by Vidispine Server are not copied. For more information about jobs, see Jobs. Note that thumbnails and poster frames are only generated if a transcode takes place.

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) – Required. A URI to the asset map that will be imported. Tracks referenced by the asset map should be located in the same folder.
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • growing (boolean) –
    • true - Specifies that the input file is still written to, so enables growing file support.
    • false (default) - No growing file handling of import file.
  • xmpfile (string) – URI to a sidecar XMP metadata file.
  • sidecar (string) – URIs or file ids of any sidecar files to import to the item.
  • settings (string) – Pre-configured import settings.
  • 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.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • noCPLreimport (boolean) – If true, do not allow reimport of CPL with same id. Default is false
Accepts:
  • application/xml, application/jsonMetadataDocument, initial metadata that is given to the imported item.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

The importtag query parameter either be a list of shapes, or on the format uuid=tag. The IMF import job accepts certain special jobMetadata parameters:

imfDisallowImportOfCPLWithoutShapeTag
If set to true, do not accept imports of CPLs which do not match any import tags (see importtag above).
imfDisallowImportOfIMPWithMissingMedia
If set to true, do not accept imports of CPLs which contains references to media not in the CPL and not already in Vidispine.
skipImpValidation

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

New in version 5.3.

Find destination storage

New in version 4.15.

GET /import/storage

Find where imported content would be stored according to current storage rules.

Query Parameters:
  • item (string) – Item id
  • tag (string) – Shape tag
  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_import

Placeholder imports

A placeholder import is an import where the item and a shape are created before any file is transferred. Once all the specified files have been transferred, an import job will start.

Create a placeholder item

POST /import/placeholder

Creates an empty item and a shape with components matching the given parameters.

Query Parameters:
  • container (integer) – The number of files that contain container components.
  • audio (integer) – The number of files that contain audio components.
  • video (integer) – The number of files that contain video components.
  • binary (integer) – The number of files that contain binary components.
  • subtitle (integer) – The number of files that contain subtitle components.
  • type (string) –
    • image-sequence- Image sequence.
    • dpx - DPX sequence.

    Deprecated since version 4.6: Import image sequences using URIs with file fragments instead.

  • frameDuration (string) – duration for each image in the sequence.
  • settings (string) – Pre-configured import settings.
  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
  • externalId (string) – An external identifier to assign to the item.
Accepts:
  • application/xml, application/jsonMetadataDocument, initial metadata that is given to the imported item.
Produces:
  • text/plain – The id of the item
  • application/xml, application/jsonItemDocument
Role:

_import

Import to a placeholder item

POST /import/placeholder/(item-id)/(component-type)

Imports the file and extracts component data based on what type is specified (container, audio, video, binary, subtitle). No transcoding will take place until all files have been imported.

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[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • growing (boolean) –
    • true - Specifies that the input file is still written to, so enables growing file support.
    • false (default) - No growing file handling of import file.
  • 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.
  • settings (string) – Pre-configured import settings.
  • index (integer) – The component index (track) of new component.
  • shapeId (string) – Shape id for which shape to receive the content.
  • 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:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Import to a placeholder item using the request body

POST /import/placeholder/(item-id)/(component-type)/raw

Imports the file and extracts component data based on what type is specified (container, audio, video, binary, subtitle). No transcoding will take place until all files have been imported.

Query Parameters:
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • createThumbnails (boolean) –
    • true (default) - Generate thumbnails as per defined by shape tag.
    • false - Disable thumbnail generation.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • createPosters (string) – A list of time codes to use for creating posters.
  • 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.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • 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.
  • 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.
  • index (integer) – Index (order) of the component.
  • shapeId (string) – Shape id for which shape to receive the content.
  • 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.
Status Codes:
  • 400 – If the amount of data received does not match the given Content-Length header.
Request Headers:
  • index – Offset (in bytes) of the full file for where the first byte of this transfer is located.
  • size – The total size of the full file.
Accepts:
  • application/octet-stream – The raw data.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job, or no content if the transfer is not finished.
Role:

_import

Example

Creating a placeholder item that consists of one file.

POST /import/placeholder?container=1
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan end="+INF" start="-INF">
      <field>
      <name>title</name>
         <value>My placeholder import!</value>
      </field>
   </timespan>
</MetadataDocument>
VX-1134
POST /import/placeholder/VX-1134/container?tag=lowres&uri=http://example.com/video.avi
Content-Type: application/xml

<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <jobId>VX-1299</jobId>
   <user>admin</user>
   <started>2010-05-07T16:12:10.023+02:00</started>
   <status>READY</status>
   <type>PLACEHOLDER_IMPORT</type>
   <priority>MEDIUM</priority>
</JobDocument>

Import to a placeholder item in bulk

POST /import/placeholder/(item-id)

Imports the files and extracts component data based on what type is specified (container, audio, video, binary, subtitle). No transcoding will take place until all files have been imported.

Query Parameters:
  • tag (string[]) – A list of shape tags to use for transcoding.
  • original (string) – If specified, should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
  • no-transcode (boolean) –
    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.
    • false (default) - Normal transcode.
  • overrideFastStart (boolean) –
    • true (default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.
    • false - Do not use the transcoder’s estimate of the duration.
  • requireFastStart (boolean) –
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength (string) – Estimated duration of the clip in seconds.
  • storageId (string) – Identifier of storage where essence file is to be stored.
  • resourceId (string) – The transcoder resource to use to execute the transcode.
  • growing (boolean) –
    • true - Specifies that the input file is still written to, so enables growing file support.
    • false (default) - No growing file handling of import file.
  • settings (string) – Pre-configured import settings.
  • 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.
  • index (integer) – The component index (track) of new component.
  • shapeId (string) – Shape id for which shape to receive the content.
  • 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.
Accepts:
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Create passkey for placeholder item

POST /import/placeholder/(item-id)/raw-passkey

Creates a new passkey for a specific placeholder item, that can be used to perform imports to this item without requiring authentication.

Query Parameters:
  • shapeId (string) – Shape id for which shape to receive the content.
Produces:

Example

POST /import/placeholder/VX-25182/raw-passkey
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <uri>a8c87f5fa49344ba0bc3575616e047da426991addd6b23d7f7c7b05a21a4a083</uri>
</URIListDocument>

Adopt stand-alone files

POST /import/placeholder/(item-id)/(component-type)/adopt/(file-id)

Adopt the file as a component in a placeholder item. The value of component-type is one of: container, audio, video, binary

Query Parameters:
  • index (integer) – Index (order) of the component.
  • shapeId (string) – Shape id for which shape to receive the content.
Role:

_import

Importing sidecar files

Sidecar files can be imported and saved as metadata of an item using a sidecar import job. The supported sidecar file formats are:

  • EVS (.evs)
  • SCC (.scc)
  • SRT (.srt)
  • STL (.stl) - EBU STL format (EBU Tech 3264).
  • XMP (.xmp)
  • Vidispine metadata (.xml)
  • WEBVTT (.vtt)

Note that this may be a lossy operation, that is, that only parts of the data from the sidecar file is saved in the item metadata, and that it may not be possible to recreate the original sidecar file from the item metadata.

Import a sidecar file

POST /import/sidecar/(item-id)

Starts a job that imports the sidecar file, located at the given URL, to the specified item.

Query Parameters:
  • sidecar (string) – Either the id of the sidecar file or a URL for locating it.
  • startTimeCode (string) – The expected start time code of the content. Can be used when importing SCC subtitles to a placeholder item to adjust the absolute time code of the SCC to relative (zero-based) timecodes. This require the configuration property useAbsoluteSccTimeCode to be set to false (default).
  • componentImport (boolean) –

    New in version 23.2.

    • true - Import sidecar file as a subtitle component.
    • false (default) - Only save data from the sidecar file in the item metadata.
  • 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

POST /import/sidecar/(item-id)/raw

Starts a job that imports the sidecar file as HTTP request body. The sidecar file will be saved in one of the Vidispine storages.

Query Parameters:
  • storageId (string) – The id of the storage that the sidecar file will be saved in.
  • fileExtension (string) – The extension of the file that this sidecar data is from. Used to identify the sidecar media type. Example: srt.
  • startTimeCode (string) – The expected start time code of the content. Can be used when importing SCC subtitles to a placeholder item to adjust the absolute time code of the SCC to relative (zero-based) timecodes. This require the configuration property useAbsoluteSccTimeCode to be set to false (default).
  • componentImport (boolean) –

    New in version 23.2.

    • true - Import sidecar file as a subtitle component.
    • false (default) - Only save data from the sidecar file in the item metadata.
  • 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 data.
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import