Documentation

Download the contents of an attachment. Use this method to download either finished output file(s) (transcripts or captions, depending on the type of order you placed), or the source file(s) for an order.

This endpoint will retrieve the latest version of the attachment, including edits, after all editor sessions for the attachment have been closed for at least two minutes.

For output file attachments, you may request to get the contents in a specific representation (file format), either via the Accept HTTP header or by appending an extension to the end of the URL.

If you optionally requested timestamps with your order, you can retrieve either in-line interval timestamps (e.g., every 30 seconds) or per word timestamps with your transcript. Per word timestamps are only available with the JSON format, all other output formats use interval timestamps.

Burned-in caption video attachments (attachment kind = burnedin) are special. The Accept header is ignored, and they are returned as-is with no conversions, and always with a video/mp4 content type. They also do not include any customer edits (if you wish, you may generate a burned-in video with customer edits reflected from within the customer caption editor).

The following representations are supported for human transcripts and AI transcripts:

{
    "speakers": [
        {"id": 1, "name": "Interviewee"},
        {"id": 2, "name": "Interviewer"}
    ],
    /* 
        Monologues (transcribed speech). 
        Each monologue corresponds to a run of text from one speaker.
    */
    "monologues": [
        {
            "id": 1,
            "speaker": 1, /* Speaker id, same as declared above */
            "speaker_name": "Interviewee", /* Speaker name, same as declared above */
            /* 
                Elements of the monologue. 
                Each element is either text (transcribed speech) 
                or a tag (an annotation), such as inaudible.

                Text elements may or may not contain a timestamp.
                Tag elements require a timestamp.
            */
            "elements": [
                {
                    /* Text element, no timestamp */
                    "type": "text",
                    /* For text elements, value contains the text */
                    "value": "I've never been here before" 
                },
                {
                    /* Tag element */
                    "type": "tag",
                    /* For tag elements, value contains the annotation type */
                    "value": "inaudible",
                    /* 
                        Timestamp format is hh:mm:sss,fff, 
                        where fff represents milliseconds 
                    */
                    "timestamp": "00:00:07,000" 
                },
                /* 
                    Text elements, with per word timestamps 
                    Whitespace and punctuation are not timestamped
                */
                {
                    "type": "text",
                    "value": " "
                },
                {
                    "type": "text",
                    "value": "so",
                    "timestamp": "00:00:20,000",
                    "end_timestamp": "00:00:20,138"
                },
                {
                    "type": "text",
                    "value": " "
                },
                {
                    "type": "text",
                    "value": "this",
                    "timestamp": "00:00:20,222",
                    "end_timestamp": "00:00:20,566"
                }
            ]
        }
    ]
}
                    

The following representations are supported for captions:

If the requested representation is not supported for the output file, then a 406 Not Acceptable status code will be returned. With the Accept header, you may specify multiple acceptable representations (as described in the Accept header HTTP spec), and the best possible match will be returned.

If you do not specify a desired representation via Accept header or URL extension, then the output file contents will be returned in its default format. For transcripts, this will be a JSON output. For captions, this will be a SubRip (.srt) file.

For source media attachments, we do not currently support multiple representations. They will always be returned in the original format in which they were uploaded. If you specify an Accept header or extension that does not match the original format, a 406 Not Acceptable status code will be returned.

For transcripts, if you request an attachment in the plain text representation (using "Accept: text/plain" header or ".txt" URL extension), you can also request a specific character encoding using the Accept-Charset HTTP header. The following encodings are supported:

If you do not specify a desired character encoding via the Accept-Charset header, then the UTF-8 encoding will be used. If something other than the plain text representation is requested, then the Accept-Charset header is ignored.

• id
  Id of the attachment to retrieve.

• offset
  Desired transcript/captions offset timestamp.

• framerate
  Desired frame rate. Can be one of the following values:
  

  • 23.98
  • 29.97NDF
  • 29.97DF

  Only supported by SCC and MCC formats

• forceCaptionGroupsToTop
  For captions, whether the groups are all forced to the top. Can be one of the following values (if none, default is false):
  

  • true
  • false

  Only supported by SCC format

• forceFirstCaptionGroupToPaintOn
  For captions, whether the first group is forced to paint-on. Can be one of the following values (if none, default is false):
  

  • true
  • false

  Only supported by SCC format

• commercialBreakDetection
  For captions, whether this order should enforce commercial break detection. Can be one of the following values (if none, default is false):
  

  • true
  • false

  Only supported by SCC format

• Authorization - contains client/user API keys
• Accept - optional, specifies a desired format for the attachment as a media type.
• Accept-Charset - optional, specifies a desired character set encoding for the attachment, if a plain text representation is requested.

• Content-Type - the content type of the attachment