Meet our new Order Promises API

• April 6, 2023

When your schedule becomes full, placing an order multiple times on the same website might become a repetitive task. It might be ok for you if you only need 1-5 videos per month, but as both volume and frequency increase, you’ll likely want to streamline the process. Connecting our systems to your own applications goes a long way to save both time and effort.

You can use our new Order Promises API to manage this integration. It provides a way for existing clients to create orders from their platforms, by means of a comprehensive programming interface consisting on a couple of methods.

Acessing the API

To gain access to our API, you must first go to your client section (Enter here) and click on the user profile to enter into your account settings.

Afterwards, click on the Api key section and generate an API key. If you don’t see this section, it’s possible that you don’t have the required permissions to view it. Talk to the administrator of your account if you want to get access to this section

Adding this key to the url of every request will allow you to use the API as you please.

Checking that everything works

To check that everything is ok, you can try a GET request to https://gapps.soustitreur.com/public/v1/order/check?apikey={YOUR_API_KEY}. When correctly done, the result will be information relating to your client account:

{
  "status": "OK",
  "data": {
    "id": 6725,
    "first_name": "Test",
    "last_name": "Test",
    "email": "test@test.com",
    "role": "user"
  }
}

We should point out that at the present state our API only supports JSON as the means of exchanging information.

Creating orders

Now that you know how our API works, you can start creating orders for us to fulfill. To do this, you can try a POST request to https://gapps.soustitreur.com/public/v1/order/new?apikey={YOUR_API_KEY}.

The JSON request body must have the following fields:

{
  "filetransfertmode": "FTP" | "GDRIVE" | "YOUTUBE",
  "videolang": "en_US" | "fr_FR" | "fr_CA" | "pt_BR" | "pt_PT" | "es_LA" | "es_ES" | "nl_NL" | "de_DE",
  "fileurl": "...",
  "rushmode": true | false,
  "proofreading": true | false,
  "tvsubtitles": true | false,
  "burnvideo": true | false,
  "translateto": [
     "en_US" | "fr_FR" | "fr_CA" | "pt_BR" | "pt_PT" | "es_LA" | "es_ES" | "nl_NL" | "de_DE",
    ...
  ],
  "edlcontent": "..." | null,
  "ordernotes": "..." | null
}

• filetransfertmode: specifies the File Transfer Mode. (see below).
• videolang: Language of the video
• fileurl: URL source of the video. Format depends on the File Transfer Mode required (see below).
• rushmode: false if you want to have a delivery in aprox. 3 days; true for delivery in 24 hours (the latter with extra charge).
• proofreading: false if you want a normal quality transcription; true if you want the transcription to be reviewed by one of our seniors (with extra charge).
• tvsubtitles: true if you want us to detect embedded text on the video and automatically mark subtitles that should change position (with extra charge)
• burnvideo: true if you want us to embed subtitles on your video (with extra charge).
• translateto: list of languages you want us to translate your subtitles in (extra charge per translation). It can be empty if no translation is needed.
• edlcontent: Contents of the EDL file as text. This allows us to align your subtitles with the cuts specified in your project.
• ordernotes: special requests to be done with your order, separated by new lines. You can add a variety of specifications to these notes, but there are also some that are automatically handled by our system. For instance:
  • CENSOR: censors your subtitles (only available for French, English and Spanish).
  • {number of lines}l{number of characters per line}c: specifies a format in number of lines and characters per line (e.g. 1l15c means one line of up to 15 characters).
  • NO_SIGNATURE or pas de signature: takes away the signature we automatically add to the end of every video.
  • frontsignature: puts the automatically added signature at the beginning of the subtitles.

A successful request to this endpoint will return the following JSON response body:

{
	"status": "OK",
	"data": {
		"ordernum": {Tracking number of your order}
	}
}

If anything goes wrong during the order creation process, the response body will take the following form:

{
	"status": "ERROR",
	"msg": "..."
}

Understanding File Transfer Modes

In order to transcribe your video, we need a way to download it from our servers. We currently support three ways to do so: downloading from an FTP server, from Google Drive, or from a Youtube link.

Creating an order from a file on an FTP server

To create an order from a video hosted on an FTP server, the filetransfertmode field must be set to FTP and the fileurl field must have any of the following formats:

• If your FTP server requires both username and password:

ftp://{URL-encoded username}:{URL-encoded password}@{FTP hostname}/{filename}

• If your FTP server requires only username:

ftp://{URL-encoded username}@{FTP hostname}/{filename}

• If your FTP server requires no authentication:

ftp://{FTP hostname}/{filename}

Make sure your file has no spaces nor special characters, and that it ends on the correct file extension.

Create an order from a file stored on Google Drive

To create an order from a video stored on Google Drive, the filetransfertmode field must be set to GDRIVE and the fileurl field must be a sharable url. Make sure the file is publicly available, because on the contrary we won’t be able to obtain it.

Create an order from a Youtube link

To create an order from a Youtube link, the filetransfertmode field must be set to YOUTUBE and the fileurl field must be a link to a non-private Youtube link.

Create an order from a Public URL

To create an order from a public URL, the filetransfertmode field must be set to PUBLICURL and the fileurl field must be a link to a file stored on a web server. Make sure the media file can be accessed via HTTP or HTTPS.

Upload your video and audio files

Checking the status of your order

Once your order has been placed, it will take some time before we start working on it. Maybe you want to check how everything is going, and as soon as the work is done, download the result for your own use.

Or it might be the case that we couldn’t successfully process your request completely. Maybe your FTP credentials were wrong, or the Google Drive or Youtube video wasn’t public and we couldn’t download it.

To tackle these cases, you can send a GET request to the following URL: https://gapps.soustitreur.com/public/v1/order/status?apikey={YOUR_API_KEY}&ordernum={Tracking number of your order}

A successful request to this endpoint will return the following JSON response body:

{
  "status": "OK",
  "data": {
    "orderstatus": "DONE" | "WAITING_FOR_DISPATCH" | "DOWNLOADED_BY_SOUSTITREUR",
    "files": [
      {
        "title": "...",
        "tasktype": "TRANSLATION" | "TRANSCRIPTION",
        "duration": {number},
        "mediafile": "...",
        "lang": "en_US" | "fr_FR" | "fr_CA" | "pt_BR" | "pt_PT" | "es_LA" | "es_ES" | "nl_NL" | "de_DE",
        "burnedvideofile": "..." | null,
        "taskdone": true | false,
        "editorlink": "..." | null,
        "downloadables": [
			{
				"category": "...",
				"type": "...",
				"url": "..."
			},
			...
		]
      },
	  ...
    ]
  }
}

• orderstatus: Current status of the order. It can have any of these three values:
  1. WAITING_FOR_DISPATCH: Your order has just entered our system. No work has been started on it.
  2. DOWNLOADED_BY_SOUSTITREUR: Our team has started working on your order. There might be some finished transcripts or translations.
  3. DONE: Your order has been completed. All non-cancelled transcripts and translations have been finished.
• files: List of transcriptions and translations sent to our. Every file has the following fields:
  • title: Title of the video.
  • tasktype: Type of item. Can be either TRANSLATION or TRANSCRIPTION.
  • duration: Duration of the video in number of seconds.
  • mediafile: Link to watch video.
  • lang: Language of video.
  • burnedvideofile: Video with embedded subtitles (only not null if ordered).
  • editorlink: Link to editor. It is not null once the item is fully transcribed or translated.
  • downloadables: List of files available to download, like Multi-platform SRT, text transcript, Adobe Premiere SRT, VTT files, etc.

If your request couldn’t be fulfilled, the response body will contain a msg field similar to the one in the previous endpoint, explaining the reason why the order couldn’t be placed:

{
	"status": "ERROR",
	"msg": "..."
}