Operations

POST /orders

Summary Submit a new caption order
URL /api/v1/orders
Detailed Description Submit a new order for captioning. The order request contains two main elements:
  • Caption options. This section contains references to the input media to be captioned, as the format for the caption file you would like us to produce.

    There are three options for specifying input media:

    • A uri returned from a POST to /inputs in the Location header. Use this if your media is either stored in your system, or is accessible at a URL where we can download it. First, make a POST to /inputs to send us the media. Next, you can use the returned uri to reference it in the order request.
    • A uri describing a location in S3. If your media is already in S3, our system can pull it from there directly, as long as it is public or has a bucket policy that allows us to download files from it.
      The format for a s3 URI is
      urn:s3:[bucket name]object
      So an example URI might be
      urn:s3:[rev-test-bucket]uploads/2013-10-11/sample.mp4
      To enable our system to pull from your S3 bucket, see Setting up S3 Bucket Policy
    • external_link - this should be used for the case where you have a link to a web page where the media is embedded, but not a link to the media file as well. We do not attempt to do anything with the link specified this way at the time the API call is made. This is in contrast to when you post to /inputs with a link to a media file - in that case we do download the file. So the external_link should only be used when you can't link to the media file directly. An example would be videos stored on YouTube or Vimeo.
      If the external_link points to a YouTube page, we can determine the duration of the video on that page automatically. Otherwise, you will need to specify the media duration explicitly.

    For each input, you must provide either uri or external_link, but not both. If both or neither is provided, an error is returned.

    For each input, You may explicitly specify the video length, in seconds, of the video referenced by the input. If you do not specify the video length, we will attempt to determine it automatically from the input media; however we are not always able to do so. We can generally calculate video length of files using common video formats (e.g. mp4, quicktime, etc) that are up to 10MB in size. If your files are larger than 10MB or are using an uncommon video format, we strongly recommend you specify the video length explicitly.

    You can also, optionally, specify the desired file formats for the finished caption files. We support these formats:

    Constant Value File Format Description
    SubRip SubRip SubRip, a simple subtitle text format first used by the SubRip program. More info.
    Scc Scenarist Scenarist Closed Caption, an older but popular format, used by many video authoring tools such as Adobe Premiere. More info.
    Mcc MacCaption The MacCaption (.mcc) format is used for high-definition Broadcast TV. Rev supports the 29.97 fps frame rate and 708 encoding for .mcc files.
    Ttml Timed Text Timed Text Markup Language, a W3C standard for specifying timed text to be displayed along with video. More info.
    QTtext Quicktime Timed Text Quicktime Timed Text, a proprietary text-based format for specifying timed text supported by Apple's Quicktime Authoring software. More info.
    Transcript Transcript Plain-text format
    WebVtt WebVTT The WebVTT (Web Video Text Tracks) format is intended for marking up external text track resources. The main use for WebVTT files is captioning or subtitling video content. More info.
    Dfxp DFXP The Distribution Format Exchange Profile is intended to be used for the purpose of transcoding or exchanging timed text information among legacy distribution content formats presently in use for subtitling and captioning functions. More info.
    CheetahCap Cheetah .CAP File format for Cheetah Captivator Offline
    Stl Spruce Subtitle File Spruce Subtitle File, a simple subtitle text format, originally used by DVD Studio Pro. More info.
    AvidDs Avid DS Subtitle File Avid DS Subtitle File, a captions file format for Avid DS Software
    FacebookSubRip Facebook ready SubRip Standard SubRip file with Facebook file naming conventions. More info.

    Specifying these formats in the order request is optional - internally we produce the captions in a canonical format and can then export them on-the-fly as any of the above formats. However, if you specify the formats in the order request, then our team can make sure the produced captions are optimized for your desired formats, so we recommend doing so if the desired formats are known. By default, we optimize for SubRip.

    Optionally, you may specify a list of language codes if you need foreign-language subtitles. You can order subtitles for these language codes: es, pt-br, fr, de, zh-si, zh-tr, ar, nl, ru, and it.

  • Notification Info. Optionally you may request that an HTTP post be made to a url of your choice when the order enters a new status (eg being captioned) and when it is complete.

Payment will be done by debiting the user's account balance.

Request Headers
  • Authorization - contains client/user API keys
Request Body XML or JSON with the details about the order. See below for an example entity illustrating the fields used.
Response On success, 201 Created.
On error, 400 Bad Request.
Response Headers
  • Location – URI identifying the newly created order. This URI can be used to request details (such as status) of the order. Only present if a 201 response code is returned
Response Body On success, empty. On error, will contain an <error/> entity with more details.
Error Codes
  • 10001 Missing Inputs - if the order request did not contain any input media
  • 10002 Invalid Input - if one of the input media URIs is invalid, eg does not identify a valid media uploaded via a POST to /inputs
  • 10003 Multiple Service Options Specified - currently, an order can be made for only one of the services we offer (transcription and caption). The service is specified by including a transcription_options, or caption_options element. If more than one such element is included in the request, this error is returned.
  • 10004 Service type is not specified - you must include exactly one of transcription_options or caption_options elements. If none of these are included, this error is returned.
  • 10005 External Link and URI specified - only External Link or URI should be set for input media
  • 10006 Input Location is not specified - neither of External Link and URI set for input media
  • 10007 Cannot connect to the External Link provided
  • 20001 Invalid Media Length - If one of the input medias has a specified video length that is not a positive integer. This will also be returned if you do not provide the video length and we are unable to calculate it automatically
  • 20003 Invalid Language Code - One or more of the provided language codes are invalid
  • 20004 Incompatible Language - Some of the selected output file formats do not support one or more of the specified languages. For example, Scenarist (Scc), MacCaptions (Mcc) and CheetahCap (CAP) are incompatible with languages that use non-latin alphabets.
  • 20010 Reference Number Too Long Code - the reference number provided longer than 256 characters
  • 30010 Ineligible For Balance Payments - if the user on whose behalf the order request was made is not eligible for paying using account balance
  • 30011 Account Balance Limit Exceeded - if the order request specified payment using account balance, but doing so would exceed the user's balance limit
  • 50000 Field Validation Errors - One or more of the fields are in the wrong format
Annotated sample request
{
    /* Optional, a reference number for the order meaningful for the client */
    "client_ref": "XB432423",
    /* 
       Optional, specify that normal turnaround time is not needed.
       By default, normal turnaround time (false) is assumed.
       Note that this value is used as a guideline only.
    */
    "non_standard_tat_guarantee": "false",
    /*
       Mandatory, provides information on what needs to be captioned and
       specified the desired captions output format.
    */
    "caption_options": {
        /*
           Mandatory, contains list of media to caption.
           Must have at least one element
        */
        "inputs": [
            {
                /*
                    Length of video, in seconds rounded up. 
                */
                "video_length_seconds": 600,
                /*
                    URI of the media, as returned from the call to POST /inputs
                */,
                "uri": "urn:rev:inputmedia:467432fds"
            },
            {
                /*
                    URI of the media stored in an S3 bucket. 
                    We will try to calculate the video length automatically.
                */,
                "uri": "urn:s3:[rev-test-bucket]uploads/2013-10-11/sample.mp3"
            },
            {
                /*
                    YouTube URL, video length determined automatically.
                */
                "external_link": "http://www.youtube.com/watch?v=UF8uR6Z6KLc"
            },
            {
                /*
                    For any other external URL, 
                    video length in seconds is required.
                */
                "video_length_seconds": 300,
                "external_link": "https://vimeo.com/7976699"
            }
        ],
        /*
          Optional, language codes to request foreign language subtitles.
         */
         "subtitle_languages": [ "es", "it" ],
        /*
           Optional, what file formats should the captions be optimized for.
           See table in description section for supported formats.
           By default, we optimize for SubRip.
        */
        "output_file_formats": [ "Scc", "SubRip" ]
    },
    /*
      Optional, enables receiving notifications about the order status
    */
    "notification": {
        /*
            The url for notifications.
            Mandatory if the notifications element is used.
            Updates will be posted to this URL
        */
        "url": "http://www.clientsite.com/orderupdate",
        /*
           Optional, specifies which notifications are sent. If "Detailed",
           then a notification is sent whenever the order is in a new status
           or has a new comment. If "FinalOnly" (the default), notification is
           sent only when the order is complete.
        */
        "level": "Detailed"
    }
}
<order_request>
    <!--
       Optional, a reference number for the order meaningful for the client
    -->
    <client_ref>XB432423</client_ref>
    <!--
       Optional, specify that normal turnaround time is not needed.
       By default, normal turnaround time (false) is assumed.
       Note that this value is used as a guideline only.
    -->
    <non_standard_tat_guarantee>false</non_standard_tat_guarantee>
    <!--
       Mandatory, provides information on what needs to be captioned and
       specified the desired captions output format.
    -->
    <caption_options>
        <!--
           Mandatory, contains list of media to caption.
           Must have at least one element
        -->
        <inputs>
            <input>
                <!--
                    Length of video, in seconds rounded up. 
                 -->
                <video_length_seconds>600</video_length_seconds>
                <!--
                   Mandatory, URI of the media, as returned from the call
                   to POST /inputs
                -->
                <uri>urn:rev:inputmedia:467432fds</uri>
            </input>
            <input>
                <video_length_seconds>600</video_length_seconds>
                <!--
                    URI of the media stored in an S3 bucket. 
                    We will try to calculate the video length automatically.
                -->
                <uri>urn:s3:[rev-test-bucket]uploads/2013-10-11/sample.mp4</uri>
            </input>
            <input>
                <!--
                   YouTube URL, video length determined automatically.
                -->
                <external_link>http://www.youtube.com/watch?v=UF8uR6Z6KLc</external_link>
            </input>
            <input>
                <!--
                   For any other external URL video length is mandatory
                -->
                <video_length_seconds>300</video_length_seconds>
                <external_link>https://vimeo.com/7976699</external_link>
            </input>
        </inputs>
        <!--
           Optional, language codes to request foreign language subtitles.
        -->
        <subtitle_languages>
          <language>es</language>
          <language>it</language>
        </subtitle_languages>
        <!--
           Mandatory, what file format should the captions be produced in. 
           See table in description section for supported formats.
        -->
        <caption_file_format>true</caption_file_format>
    </caption_options>
    <!--
      Optional, enables receiving notifications about the order status
      -->
    <notification>
        <!--
            The url for notifications.
            Mandatory if the notifications element is used.
            Updates will be posted to this URL
        -->
        <url>http://www.clientsite.com/orderupdate</url>
        <!--
           Optional, specifies which notifications are sent. If "Detailed",
           then a notification is sent whenever the order is in a new
           status or has a new comment. If "FinalOnly" (the default),
           notification is sent only when the order is complete.
        -->
        <level>Detailed</level>
    </notification>
</order_request>