Imports

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. For more information about jobs, see Jobs. Note that thumbnails and poster frames are only generated if a transcode takes place.

Query Parameters:
 
  • uri – A URI to the file that will be imported. See also URI’s, URL’s, and Special Characters.
  • URL – A URL to the file that will be imported. (Deprecated since x.)
  • tag – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • thumbnails
    • true (default) - Generate thumbnails as per defined by shape tag
    • false - Disable thumbnail generation
  • thumbnailService – An optional identifier to which thumbnail resource that should be used.
  • createPosters – An optional list of time codes to use for creating posters.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • storageId – Optional identifier of storage where essence file is to be stored.
  • filename – The filename to be stored as original filename. Optional.
  • growing
    • 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 – An optional URI to a sidecar XMP metadata file.
  • sidecar – Optional URIs or file ids of any sidecar files to import to the item. (New in 4.0.)
  • no-transcode
    • 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.
  • notification – See Notifications . (Optional)
  • notificationData – See Notifications . (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task. See Special job metadata values
Accepts:
  • application/xml, application/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>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 – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • thumbnails
    • true (default) - Generate thumbnails as per defined by shape tag
    • false - Disable thumbnail generation
  • thumbnailService – An optional identifier to which thumbnail resource that should be used.
  • createPosters – An optional list of time codes to use for creating posters.
  • 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.
  • storageId – Optional identifier of storage where essence file is to be stored.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • 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
  • filename – The filename to be stored as original filename. Optional.
Status Codes:
  • 400

    If the amount of data received does not match the given Content-Length header.

    New in version 4.2.3.

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 – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • thumbnails
    • true (default) - Generate thumbnails as per defined by shape tag
    • false - Disable thumbnail generation
  • thumbnailService – An optional identifier to which thumbnail resource that should be used.
  • createPosters – An optional list of time codes to use for creating posters.
  • 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.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • filename – The filename to be stored as original filename. Optional.
  • 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
  • settings – Pre-configured import settings. See Import settings
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/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 /import/raw

Imports the item and starts the job.

Query Parameters:
 
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • filename – The filename to be stored as original filename. Optional.
  • 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
  • settings – Pre-configured import settings. See Import settings
  • tag – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • thumbnails
    • true (default) - Generate thumbnails as per defined by shape tag
    • false - Disable thumbnail generation
  • thumbnailService – An optional identifier to which thumbnail resource that should be used.
  • createPosters – An optional list of time codes to use for creating posters.
  • 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.
  • storageId – Optional identifier of storage where essence file is to be stored.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • filename – The filename to be stored as original filename. Optional.
  • 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
  • settings – Pre-configured import settings. See Import settings
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/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?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>

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.
  • type

    Optional string.

    • image-sequence- Image sequence.
    • dpx - DPX sequence.
  • frameDuration – Optional Time durations for each image in the sequence (optional).
  • no-transcode
    • 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.
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)/[container,audio,video]

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

Query Parameters:
 
  • uri – A URI to the file that will be imported. See also URI’s, URL’s, and Special Characters. Must be specified unless fileId is specified.
  • fileId – The id of the file that contains the essence. Must be specified unless uri is specified.
  • tag – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • growing
    • 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 – 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
  • settings – Pre-configured import settings. See Import settings
  • index – The component index (track) of new component.
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)/[container,audio,video]/raw

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

Query Parameters:
 
  • tag – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • 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.
  • storageId – Optional identifier of storage where essence file is to be stored.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • filename – The filename to be stored as original filename. Optional.
  • 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
  • settings – Pre-configured import settings. See Import settings
Status Codes:
  • 400

    If the amount of data received does not match the given Content-Length header.

    New in version 4.2.3.

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). No transcoding will take place until all files have been imported.

Query Parameters:
 
  • tag – An optional list of shape tags to use for transcoding.
  • original – An optional tag, if specified it 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.
  • overrideFastStart
    • 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
    • true (default) - Try to put the index tables (header) in front of the file.
    • false - Put header at end of file.
  • fastStartLength – Optional estimated duration of the clip in seconds.
  • storageId – Optional identifier of storage where essence file is to be stored.
  • growing
    • 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 – Pre-configured import settings. See Import settings
  • notification – See Notifications . (Optional)
  • notificationData – See Notifications . (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task. See Special job metadata values
Accepts:
Produces:
  • application/xml, application/json – A JobDocument that describes the import job.
Role:

_import

Adopt stand-alone files

POST /import/placeholder/(item-id)/container/adopt/(file-id)

Adopt the file as a container component in a placeholder item.

Role:_import

Importing sidecar files

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 – Either the file id of the sidecar file or a URL for locating it.
  • 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

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 – The id of the storage that the sidecar file will be saved.
  • 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.
Status Codes:
  • 400

    If the amount of data received does not match the given Content-Length header.

    New in version 4.2.3.

Role:

_import