This is a step-by-step guide for getting started with the Vidispine API. The purpose of this guide is to let you familiarize yourself with the system, and help you programmatically create your first item, shape and metadata-field, import and transcode a file, and finally retrieve the transcoded version of the file through the API.
Before you begin
- This guide assumes that Vidispine is installed on http://localhost:8080/API
- Default header should be content-type:application/xml
- Default authentication is basic authentication
- Default credentials for access to /API are u: admin p: admin
IntroductionThe Vidispine .NET SDK is a powerful building block for developing video applications and services using .NET. However, Vidispine can be controlled by other means as well. For debugging and/or playing around it is good to be able to send REST API requests directly. There are thousands of tools out there, but some that have been proven to work very well are:
- Google Postman, comes with an easy to use user interface, ability to save requests.
- cURL, expert's tool and the Swiss army knife of HTTP requests. Command-line tool.
- HTTPie, also a command-line tool but easier to use than cURL. Requires python. There is no one-click installer, but there are several blog posts with easy step-by-step guides.
- Your favourite browser. Easy to use, but quite limited in terms of HTTP details.
Create a shapeWhen importing a file to Vidispine you might want to create proxy (lowres) versions of your content. To enable this, you must create a shape to hold the item. The easiest way to start is to use the builtin shape tag settings, see API documentation on Shape Tag. To set up the presets, make a PUT request to:
http://localhost:8080/APIinit/preset-templatesYou can view all your shapes by making a GET request to
http://localhost:8080/API/shape-tag/, e.g. by using your browser. All details for a shape is given by a GET request to
Create a custom metadata fieldWhen building an database with Vidispine you will need to master how to create metadata fields. Here's an example creating the text field "legal_copyright": Make a PUT request to
<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <type>string</type> </MetadataFieldDocument>
Note: Custom metadata fields must have the format prefix_name (with the underscore inbetween). Read more on creating metadata fields, allowed types etc in the metadata example in the API documentation.
You can view metadata fields in your system by making a GET request to
This will return:
Import a fileNow, let's import a file with one custom metadata field and tell Vidispine to create a proxy version. When importing a file, Vidispine needs to be able to reach the local (or remote) source file (as file:/// or http://). The below example shows importing "NASA1.mov" from the local harddrive setting the system metadata tag "title" to "Nasa1", and setting the custom metadata tag "legal_copyright" to "http://www.nasa.gov". Also, we will add the command tag=__mp4 to the URL to create an mp4-proxy-version of the file. Make a POST to
http://localhost:8080/API/import?URL=file:///C:/Vidispine/Demovideos/NASA1.mov&tag=__mp4(Note the forwardslash in the Windows file path!) with body
<MetadataDocument xmlns=”http://xml.vidispine.com/schema/vidispine”> <timespan start=”-INF” end=”+INF”> <field> <name>title</name> <value>Nasa1</value> </field> <field> <name>legal_copyright</name> <value>www.nasa.gov</value> </field> </timespan> </MetadataDocument>
This will now trigger the file to be imported, creating one shape for the original file and one shape for the proxy version, as well as a set of thumbnail URL's.The return data from the POST contains the job-id (e.g. VX-20) which you can use to monitor the job and determine the ItemID (in this case VX-6) created for your imported item.
Monitoring jobsYou can monitor what's going on with your import job created in the previous step: Make a GET request to
http://localhost:8080/API/job/VX-20This will return a document with details on all steps performed and their outcome. In this case, the job is finished with success. And we can see that the imported item got the ItemID VX-6:
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <jobId>VX-20</jobId> <user>admin</user> <started>2015-05-28T11:39:23.572Z</started> <status>FINISHED</status> <type>PLACEHOLDER_IMPORT</type> <priority>MEDIUM</priority> <currentStep> <description>Importing sidecar files.</description> <number>16</number> <status>FINISHED</status> </currentStep> <data> <key>item</key> <value>VX-6</value> </data> <totalSteps>16</totalSteps> <log> ... </log> </JobDocument>
Note: The XML is somewhat shortened
View Item dataWhen the import job has finished, you can see the complete result by: Make a GET request to
http://localhost:8080/API/item/VX-6?content=metadata,thumbnail,shapeIn the return document there should be two shapes, in this case VX-8 for the lowres and VX-7 for the original. There's also a set of thumbnails. In the metadata section you will find the custom field legal_copyright with the value provided when importing the file. Example (thumbnails section shortened)
<ItemDocument xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-6"> <metadata> <revision>VX-28,VX-27,VX-30,VX-32,VX-34,VX-33</revision> <timespan start="-INF" end="+INF"> <field uuid="24044ded-ee16-477a-990c-159a3ae0d3b3" user="admin" timestamp="2012-03-29T16:24:11.350+02:00" change="VX-27"> <name>legal_copyright</name> <value uuid="ec273429-53b8-4220-a081-79c0447f4dbc" user="admin" timestamp="2012-03-29T16:24:11.350+02:00" change="VX-27">www.nasa.gov</value> </field> </timespan> </metadata> <thumbnails>...</thumbnails> <shape> <id>VX-8</id> <essenceVersion>0</essenceVersion> <tag>__mp4</tag> <mimeType>video/mp4</mimeType> <containerComponent>...</containerComponent> <audioComponent>...</audioComponent> <videoComponent>...</videoComponent> </shape> <shape> <id>VX-7</id> <essenceVersion>0</essenceVersion> <tag>original</tag> <mimeType>video/quicktime</mimeType> <containerComponent>...</containerComponent> <audioComponent>...</audioComponent> <videoComponent>...</videoComponent> </shape> </ItemDocument>
Access proxy version over httpNow, let's access the proxy version of our uploaded file. Vidispine supports creating 5-minute temporary URL's for streaming files through the API without authentication. The following command creates unique URLs for all available versions (shapes) of an item: Make a GET to
This will return:
<ItemDocument xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-6"> <files> <uri>http://localhost:8080/APInoauth/storage/VX-1/file/VX-24/0.5103167573574195/VX-24.mp4</uri> <uri>http://localhost:8080/APInoauth/storage/VX-1/file/VX-23/0.16017109612757396/VX-23.mov</uri> </files> </ItemDocument>
The URL's will be valid for 5 minutes. This concludes the getting started guide.
So, where do I go from here?
For more details on what you can do with the API, check out our the API documentation, this is the Holy Bible for the API. In the knowledge base of our Support Forum, i.e., this web-site, you can find a lot of useful tips and tricks, questions and answers, how-to's et cetera, which can guide you even further. You can also sign-up to the Support Forum (this web-site) to get help directly from our developers.