Skip to main content

Service

The Service API allows clients to start a service like transcription or translation on a media item. The user can also get the status of the service job.

How it Works​

Clients provide a media item id to the Subly Start Service API with the service details. Subly then starts the requested service on the input media.

What You Need​

Clients of the Start Service API will need:

  • An API key to use in header x-api-key for all requests.
  • The x-api-key header set with the API key received at registration.
  • The mediaId of the media item to start the service on.

Endpoints

All API requests require the x-api-key header to be set with the API key received at registration.

API paths use base URL https://api.getsubly.com/v2

Start Service Request​

Start a service on a media item.

Endpoint: POST /media/{mediaId}/service

Body Format: Content-Type: application/json

Path Parameters:

  • mediaId (string): ID of the media item to start the service on.

Body​

  • services (array): List of service items to start on the media item

Service Item​

Each service item has the following common properties:

  • serviceType (string): Type of service to start e.g. "TRANSCRIBE", "TRANSLATE" (see details at Service Types)
  • serviceCategory (string): Category of the service e.g. "AI" (see details at Service Categories)

Transcribe Service​

  • serviceType: "TRANSCRIBE"
  • serviceCategory (string): Category of the service e.g. "AI" (see details at Service Categories)
  • language (string): Language code for the media to transcribe (see supported languages at Language (Transcribe))
  • glossary (array): List of glossary terms for transcribe
  • maxCharsPerLine (number - optional): Maximum number of characters per line (CPL) in the transcription
  • maxCharsPerSecond (number - optional): Maximum number of characters per second (CPS) in the transcription

Translate Service​

  • serviceType: "TRANSLATE"
  • serviceCategory (string): Category of the service e.g. "AI" (see details at Service Categories)
  • language (string): Language code to translate to (see supported languages at Language (Translate))
  • glossary (array): List of glossary terms for translate
  • glossary.source (object): Source language and word
  • glossary.source.language (string): Language code of the source word
  • glossary.source.word (string): Source word
  • glossary.target (object): Target language and word
  • glossary.target.language (string): Language code of the target word
  • glossary.target.word (string): Target word

Example​

{
  "services": [
    {
      "serviceType": "TRANSCRIBE",
      "language": "en-US",
      "serviceCategory": "AI",
      "glossary": ["technical term 1", "technical term 2"]
    },
    {
      "serviceType": "TRANSLATE",
      "serviceCategory": "AI",
      "language": "fr",
      "glossary": [
        {
          "source": {
            "language": "en",
            "word": "car"
          },
          "target": {
            "language": "fr",
            "word": "voiture"
          }
        }
      ]
    }
  ]
}

Response​

200 status for successful request

The response of an array of service jobs started on the media item.

  • serviceId (string): Service ID of successful service job
  • serviceType (string): Type of service started (see details at Service Types)
  • serviceCategory (string): Category of the service started (see details at Service Categories)
  • language (string): Language of the service
  • errors (array - optional): List of errors if any

If the service starts successfully, the response will contain the serviceId of the service job started. If the service fails to start, the response will contain the errors array with the error details.

Get Service Request​

Get the status of a service on a media item.

Endpoint: GET /media/{mediaId}/service/{serviceId}

Response​

  • serviceId (string): ID of the service
  • status (string): Status of the service (see details at Service Statuses)
  • startedAt (string): Date and time the service was created
  • completedAt (string): Date and time the service was completed