Adding captions

In this article we provide examples of calls and responses relative to Captions jobs in Reach integration flows.

Retrieving a Captions job

Retrieving a task

Example of a response after requesting a task with the REACH profile information for a captions task using entryVendorTask.get - Kaltura VPaaS API Documentation: 

{  "id": "362949832",  "partnerId": 5486112,  "vendorPartnerId": 5484572,  "createdAt": 1692434122,  "entryId": "1_bdhcuo89",  "status": 1,  "reachProfileId": 251412,  "catalogItemId": 20692,  "accessKey": "djJ8NTQ4NjExMnwVeLqwx9fCfrPmEKXnqqFgtWd4px5kLinoEMFXiE831OqLNxklIa3JzonLxN66lgsD5LG0cMqjjOvrc1G4eahdj0-MnKK3CX3_hBtxA-0AtK4c4AU-Dp6YCDBOe4l9s-3lFRuHYaFpuRXyoEKKhUK5QqZMyWPpW_u2y_394zRAyaS8NqVBlgB1HD-sA_JLr_5IGJZntSSU4icIMAIDZaLloM8ZeIhhAwJZRG1gKw_EnQ==",  "version": 11,  "relatedObjects": {
    "reach_vendor_catalog_item": {
      "objects": [
        {
          "flavorParamsId": 0,
          "clearAudioFlavorParamsId": 0,
          "outputFormat": "3",
          "serviceType": 1,
          "serviceFeature": 9,
          "turnAroundTime": -1,
          "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
          "sourceLanguage": "English",
          "allowResubmission": false,
          "objectType": "KalturaVendorExtendedAudioDescriptionCatalogItem"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaVendorCatalogItemListResponse"
    },
    "reach_vendor_profile": {
      "objects": [
        {
          "name": "Reach test",
          "defaultOutputFormat": 1,
          "enableMetadataExtraction": true,
          "enableSpeakerChangeIndication": false,
          "enableAudioTags": false,
          "enableProfanityRemoval": true,
          "maxCharactersPerCaptionLine": 26,
          "labelAdditionForMachineServiceType": "",
          "labelAdditionForHumanServiceType": "",
          "contentDeletionPolicy": 2,
          "flavorParamsIds": "",
          "vendorTaskProcessingRegion": 1,
          "objectType": "KalturaReachProfile"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaReachProfileListResponse"
    }  },  "objectType": "KalturaEntryVendorTask"
}


Retrieving task details

Example of a response after requesting catalog item details for a captions task using vendorCatalogItem.get - Kaltura VPaaS API Documentation:

{
  "enableSpeakerId": false,
  "fixedPriceAddons": 0,
  "id": 20632,
  "vendorPartnerId": 5484572,
  "name": "Machine caption test",
  "systemName": "Machine caption test",
  "createdAt": 1691505207,
  "updatedAt": 1691505207,
  "status": 2,
  "serviceType": 2,
  "serviceFeature": 1,
  "turnAroundTime": -1,
  "pricing": {
    "pricePerUnit": 0,
    "priceFunction": "kReachUtils::calcPricePerMinute",
    "objectType": "KalturaVendorCatalogItemPricing"
  },
  "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
  "sourceLanguage": "English",
  "allowResubmission": false,
  "objectType": "KalturaVendorCaptionsCatalogItem"
}


Delivering a Captionstask

Adding captions

Example of an API call to create the caption asset using captionAsset.add - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/caption_captionasset/action/add \
    -d "ks=$KALTURA_SESSION" \
    -d "entryId=dfqqdsfdqsf" \
    -d "captionAsset[accuracy]=70" \
    -d "captionAsset[associatedTranscriptIds]=qdsfdqf" \
    -d "captionAsset[format]=1" \
    -d "captionAsset[language]=English" \
    -d "captionAsset[label]=English%20caption" \
    -d "captionAsset[isDefault]=0" \
    -d "captionAsset[objectType]=KalturaCaptionAsset"

 

Example of a response after creating a caption asset using captionAsset.add - Kaltura VPaaS API Documentation:

{
  "language": "English",
  "languageCode": "en",
  "isDefault": false,
  "label": "English caption",
  "format": "1",
  "status": 0,
  "accuracy": 80,
  "displayOnPlayer": true,
  "id": "1_qu1grtg3",
  "entryId": "1_eyl6k4e0",
  "partnerId": 5486112,
  "size": 0,
  "tags": "",
  "createdAt": 1692269501,
  "updatedAt": 1692269501,
  "sizeInBytes": 0,
  "objectType": "KalturaCaptionAsset"
}


Updating captions

Example of an API call to update the caption asset using captionAsset.update - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/caption_captionasset/action/update \
    -d "ks=$KALTURA_SESSION" \
    -d "id=1_qu1grtg3" \
    -d "captionAsset[objectType]=KalturaCaptionAsset"
    -d "captionAsset[associatedTranscriptIds]=1_5y3bwomr"


Example of a response after updating the caption file with an associated Transcript ID using captionAsset.update - Kaltura VPaaS API Documentation:

{
  "captionParamsId": 0,
  "language": "English",
  "languageCode": "en",
  "isDefault": false,
  "label": "English caption",
  "format": "1",
  "status": 2,
  "accuracy": 70,
  "displayOnPlayer": true,
  "associatedTranscriptIds": "1_5y3bwomr",
  "id": "1_t8jrk9qu",
  "entryId": "1_eyl6k4e0",
  "partnerId": 5486112,
  "version": "1",
  "size": 0,
  "tags": "",
  "fileExt": "srt",
  "createdAt": 1692269157,
  "updatedAt": 1692348167,
  "description": "",
  "sizeInBytes": "1407",
  "objectType": "KalturaCaptionAsset"
}


Transferring the caption file to Kaltura

Example of an API call to transfer the caption file to Kaltura using captionAsset.setContent - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/caption_captionasset/action/setContent \
    -d "ks=$KALTURA_SESSION" \
    -d "id=9876576" \
    -d "contentResource[objectType]=KalturaUrlResource" \
    -d "contentResource[forceAsyncDownload]=false" \
    -d "contentResource[url]=https%3A%2F%2Fwww.vendor.com%2Fdeliverable_to_upload.srt"


Example of a response after transferring the caption file to Kaltura using captionAsset.setContent - Kaltura VPaaS API Documentation:

{
  "captionParamsId": 0,
  "language": "English",
  "languageCode": "en",
  "isDefault": false,
  "label": "English caption",
  "format": "1",
  "status": 7,
  "accuracy": 70,
  "displayOnPlayer": true,
  "id": "1_t8jrk9qu",
  "entryId": "1_eyl6k4e0",
  "partnerId": 5486112,
  "version": "1",
  "size": 0,
  "tags": "",
  "createdAt": 1692269157,
  "updatedAt": 1692269331,
  "description": "",
  "sizeInBytes": 0,
  "objectType": "KalturaCaptionAsset"
}


Examples of notes and dictionary information in job details

Examples of notes in job details (in JSON format)

Example of instructions & notes in job details when instructions are submitted by the user via the REACH order GUI.

The parameter used is “notes” and the content is text:

{
  "id": "376456442",
  "partnerId": 4754682,
  "vendorPartnerId": 4754672,
  "createdAt": 1696668011,
  "entryId": "1_9l3p2hpu",
  "status": 1,
  "reachProfileId": 190012,
  "catalogItemId": 20702,
  "accessKey": "djJ8NDc1NDY4MnzXebVnyEzuYeJnSs396Ul7A4eT29n584Db7ZQhM28qNjY1fzNExN-NLl3x0jPcSaUvc3MfGtM6peZasy19Z_OazWQXoxSKn-m1KxcFrSeu3fBZSObHdVwG1SqwooaZo63_KcnCAYLnbUwUDLCm31iwxL86ZKCBJhUY2NAanwEJDTDcmgltRKt4A2BfWwDZycdCH_QGU49c345VUcr1HfF9d16Jl0ke5njLx8HEAu_ozg==",
  "version": 11,
  "notes": "astroenterology gastroenteritis gynecologist immunity intercellular protrusion inflammation paralysis sclerosis stenosis therapy",
  "relatedObjects": {
    "reach_vendor_catalog_item": {
      "objects": [
        {
          "outputFormat": "1",
          "enableSpeakerId": false,
          "serviceType": 1,
          "serviceFeature": 1,
          "turnAroundTime": 4,
          "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
          "sourceLanguage": "English",
          "allowResubmission": false,
          "objectType": "KalturaVendorCaptionsCatalogItem"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaVendorCatalogItemListResponse"
    },
    "reach_vendor_profile": {
      "objects": [
        {
          "name": "default profile",
          "defaultOutputFormat": 1,
          "enableMetadataExtraction": true,
          "enableSpeakerChangeIndication": true,
          "enableAudioTags": true,
          "enableProfanityRemoval": false,
          "maxCharactersPerCaptionLine": 26,
          "labelAdditionForMachineServiceType": "",
          "labelAdditionForHumanServiceType": "",
          "contentDeletionPolicy": 2,
          "flavorParamsIds": "",
          "vendorTaskProcessingRegion": 1,
          "objectType": "KalturaReachProfile"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaReachProfileListResponse"
    }
  },
  "objectType": "KalturaEntryVendorTask"
}


Examples of dictionary in job details (in JSON format)

Example of a dictionary in job details when a dictionary is set on a REACH profile.

The parameter used is “dictionary” and the content is words or phrases separated by carriage returns:

{
  "id": "376456672",
  "partnerId": 4754682,
  "vendorPartnerId": 4754672,
  "createdAt": 1696668170,
  "entryId": "1_h015wj3i",
  "status": 1,
  "reachProfileId": 258732,
  "catalogItemId": 13922,
  "accessKey": "djJ8NDc1NDY4MnxBO-fZ-H40cPCgCv8TdcDYiACyiKCJM7VApH5xcbdp18ZyYsusCoDbF07PuiGOjHNGqm2q9TcMbsv9qfRvI5y5fo7THRm6mIXbBZ5X5rEban_4C0vcOKLZpKb2oGBGqtGNuJyuRT6psYE3PWVOOJ229-GF4G5QwQW-eMl4nyJsCbhGTSaenbbEvEZZS3ak12cHj73RadpbLwO9NwwnRsGT0IzpyVHaCuLe10dOzfa9ug==",
  "version": 11,
  "dictionary": "Linus Sandgren\nMatthew Libatique\nChayse Irvin\nCarolyn Giardina",
  "relatedObjects": {
    "reach_vendor_catalog_item": {
      "objects": [
        {
          "outputFormat": "1",
          "enableSpeakerId": false,
          "serviceType": 2,
          "serviceFeature": 1,
          "turnAroundTime": 7200,
          "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
          "sourceLanguage": "English",
          "allowResubmission": true,
          "objectType": "KalturaVendorCaptionsCatalogItem"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaVendorCatalogItemListResponse"
    },
    "reach_vendor_profile": {
      "objects": [
        {
          "name": "profile with Speaker ID",
          "defaultOutputFormat": 1,
          "enableMetadataExtraction": true,
          "enableSpeakerChangeIndication": true,
          "enableAudioTags": false,
          "enableProfanityRemoval": true,
          "maxCharactersPerCaptionLine": 26,
          "labelAdditionForMachineServiceType": "",
          "labelAdditionForHumanServiceType": "",
          "contentDeletionPolicy": 2,
          "flavorParamsIds": "",
          "vendorTaskProcessingRegion": 1,
          "objectType": "KalturaReachProfile"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaReachProfileListResponse"
    }
  },
  "objectType": "KalturaEntryVendorTask"
}


Example of both notes and dictionary in Job details (in JSON format)

Example of a dictionary in job details when a dictionary is set on a REACH profile AND instructions are submitted by the user.

{
  "id": "376458242",
  "partnerId": 4754682,
  "vendorPartnerId": 4754672,
  "createdAt": 1696669644,
  "entryId": "1_2cut2m84",
  "status": 3,
  "reachProfileId": 258782,
  "catalogItemId": 20702,
  "accessKey": "djJ8NDc1NDY4MnycniFva04oQ40nym83FxN44eVaoJolgYFqLJnA19LUbT_aqMkSTpC8biljRDB2uxK5YNCe5a8z0dplsaQ2eyBovH4paSmtkAywU3wNN1l5fRIVK_IAImAhLNm_zomsBHOyGpchv60aZkexqr3jZSE0DHocoXxJROLot0I9sSOiTZqsu3Qy4LgXad6O4wr0vvylCnW2ntXk9d1zdIyacwJElhBwiNIhkC2hEG1c16AP0Q==",
  "version": 11,
  "notes": "No particular instructions although there is a dictionary for this profile (not usable for this exercise).",
  "dictionary": "Abrogate\nAnachronism\nArrant\nArtless\nAsperity",
  "relatedObjects": {
    "reach_vendor_catalog_item": {
      "objects": [
        {
          "outputFormat": "1",
          "enableSpeakerId": false,
          "serviceType": 1,
          "serviceFeature": 1,
          "turnAroundTime": 4,
          "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
          "sourceLanguage": "English",
          "allowResubmission": false,
          "objectType": "KalturaVendorCaptionsCatalogItem"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaVendorCatalogItemListResponse"
    },
    "reach_vendor_profile": {
      "objects": [
        {
          "name": "profile with multiple dictionaries",
          "defaultOutputFormat": 1,
          "enableMetadataExtraction": true,
          "enableSpeakerChangeIndication": false,
          "enableAudioTags": false,
          "enableProfanityRemoval": true,
          "maxCharactersPerCaptionLine": 26,
          "labelAdditionForMachineServiceType": "",
          "labelAdditionForHumanServiceType": "",
          "contentDeletionPolicy": 2,
          "flavorParamsIds": "",
          "vendorTaskProcessingRegion": 1,
          "objectType": "KalturaReachProfile"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaReachProfileListResponse"
    }
  },
  "objectType": "KalturaEntryVendorTask"
}


Label suffixes

Example of job details which includes label additions (in JSON format)

The two label additions are labelAdditionForMachineServiceType and labelAdditionForHumanServiceType :

{
  "id": "376460662",
  "partnerId": 4754682,
  "vendorPartnerId": 4754672,
  "createdAt": 1696672367,
  "entryId": "1_d3opqx7e",
  "status": 3,
  "reachProfileId": 258792,
  "catalogItemId": 13922,
  "accessKey": "djJ8NDc1NDY4MnzIXfdAk-AYe85daOUQ4u6sfdONKiUg0inAvgEWCqhtbQBt5gxrjfxWI_PgpfnvFwrmnVOpA-zfWwHnO7FkIouV9yWej1Xix6UT5Y09RXOgZD4aI2VfN0nf-m3ZshLCNFAA_yKCw57d6Rv4x2cOLQjeTPVACmYFVKpm0VGajXqOFRCDVC-9zs9KcM6jEM5Ff8Age3yW8670yyuhZLb6HhzhmRju173OJM8bxF7SuzT_LA==",
  "version": 11,
  "relatedObjects": {
    "reach_vendor_catalog_item": {
      "objects": [
        {
          "outputFormat": "1",
          "enableSpeakerId": false,
          "serviceType": 2,
          "serviceFeature": 1,
          "turnAroundTime": 7200,
          "engineType": "OpenCalaisReachVendor.OPEN_CALAIS",
          "sourceLanguage": "English",
          "allowResubmission": true,
          "objectType": "KalturaVendorCaptionsCatalogItem"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaVendorCatalogItemListResponse"
    },
    "reach_vendor_profile": {
      "objects": [
        {
          "name": "profile with label addition",
          "defaultOutputFormat": 1,
          "enableMetadataExtraction": true,
          "enableSpeakerChangeIndication": false,
          "enableAudioTags": false,
          "enableProfanityRemoval": true,
          "maxCharactersPerCaptionLine": 26,
          "labelAdditionForMachineServiceType": "ASR",
          "labelAdditionForHumanServiceType": "Human",
          "contentDeletionPolicy": 2,
          "flavorParamsIds": "",
          "vendorTaskProcessingRegion": 1,
          "objectType": "KalturaReachProfile"
        }
      ],
      "totalCount": 1,
      "objectType": "KalturaReachProfileListResponse"
    }
  },
  "objectType": "KalturaEntryVendorTask"
}


Delivering transcripts as attachments

Creating transcripts

Example of an API call to create the transcript asset using attachmentAsset.add - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/attachment_attachmentasset/action/add \
    -d "ks=$KALTURA_SESSION" \
    -d "entryId=9834897" \
    -d "attachmentAsset[objectType]=KalturaTranscriptAsset" \
    -d "attachmentAsset[accuracy]=70" \
    -d "attachmentAsset[language]=English" \
    -d "attachmentAsset[format]=1"


Example of a response after creating a transcript asset using attachmentAsset.add - Kaltura VPaaS API Documentation:

{
  "accuracy": 70,
  "language": "English",
  "format": "1",
  "status": 0,
  "id": "1_5y3bwomr",
  "entryId": "1_eyl6k4e0",
  "partnerId": 5486112,
  "size": 0,
  "tags": "",
  "createdAt": 1692347432,
  "updatedAt": 1692347432,
  "sizeInBytes": 0,
  "objectType": "KalturaTranscriptAsset"
}


Transfering transcripts to Kaltura

Example of an API call to transfer the transcript file to Kaltura using attachmentAsset.setContent - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/attachment_attachmentasset/action/setContent \
    -d "ks=$KALTURA_SESSION" \
    -d "id=978675" \
    -d "contentResource[objectType]=KalturaUrlResource" \
    -d "contentResource[forceAsyncDownload]=false" \
    -d "contentResource[url]=https%3A%2F%2Fwww.vendor.com%2Fdeliverable_to_upload.txt"


Example of a response after transferring the transcript file to Kaltura using attachmentAsset.setContent - Kaltura VPaaS API Documentation:

{
  "accuracy": 70,
  "language": "English",
  "format": "1",
  "status": 2,
  "id": "1_5y3bwomr",
  "entryId": "1_eyl6k4e0",
  "partnerId": 5486112,
  "version": "1",
  "size": 3541,
  "tags": "",
  "fileExt": "txt",
  "createdAt": 1692347432,
  "updatedAt": 1692347705,
  "description": "Failed downloading file[https://www.vendor.com/transcript.txt]",
  "sizeInBytes": "3541",
  "objectType": "KalturaTranscriptAsset"
}


Metadata extraction - Adding tags to entries

Example of an API call to update a entry with a new tag using media.update - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/media/action/update \
    -d "ks=$KALTURA_SESSION" \
    -d "entryId=1_6gj121d8" \
    -d "mediaEntry[objectType]=KalturaMediaEntry" \
    -d "mediaEntry[tags]=vendortag"


Updating jobs after delivering assets

Example of an API call to update a job using entryVendorTask.updateJob - Kaltura VPaaS API Documentation:

curl -X POST https://www.kaltura.com/api_v3/service/reach_entryvendortask/action/updateJob \
    -d "ks=$KALTURA_SESSION" \
    -d "id=234343434" \
    -d "entryVendorTask[accuracy]=70" \
    -d "entryVendorTask[catalogItemId]=873743784" \
    -d "entryVendorTask[entryId]=1_eyl6k4e0" \
    -d "entryVendorTask[errDescription]=My%20custom%20error" \
    -d "entryVendorTask[externalTaskId]=987685474" \
    -d "entryVendorTask[status]=6" \
    -d "entryVendorTask[taskJobData][objectType]=KalturaTranslationVendorTaskData" \
    -d "entryVendorTask[taskJobData][captionAssetId]=1_qu1grtg3" \
    -d "entryVendorTask[objectType]=KalturaEntryVendorTask"


Example of a response after updating a job using entryVendorTask.updateJob - Kaltura VPaaS API Documentation:

{
  "id": "360601872",
  "partnerId": 5486112,
  "vendorPartnerId": 5484572,
  "createdAt": 1691581888,
  "updatedAt": 1692174016,
  "queueTime": 1691581888,
  "finishTime": 1692174016,
  "entryId": "1_6gj121d8",
  "status": 6,
  "reachProfileId": 251412,
  "catalogItemId": 20632,
  "price": 0,
  "userId": "c82fb0fcaaaba215b7a17b9e8e7ea751",
  "errDescription": "My custom error",
  "accessKey": "djJ8NTQ4NjExMnxWmERgTx5osMFnsK08VwKPzjte1FJIOneacZO1pvRWmkMfZ-NtVCEx2TTfyqATCNP8jeSRZ-76jtJwfO53ZgV4xuJ4_N5iXvs90NOXqoUidXiRG6I_iaIHzgxmlTwnWg2t_2SviX6XZwdlC3l8jtv9DKdfcUjigLtrd5RpXWamEEPSssa8M8YKtVhgiQBNZF6HM7jhu1uO-XC5ieweOc7aNQhZFQUEg_2wmAiyuwhOcg==",
  "version": 11,
  "creationMode": 1,
  "expectedFinishTime": 1692186688,
  "serviceType": 2,
  "serviceFeature": 1,
  "turnAroundTime": -1,
  "objectType": "KalturaEntryVendorTask"
}




Was this article helpful?
Thank you for your feedback!
In This Article
Related Articles
Back to top

Never miss a thing!

Subscribe to our customer newsletter and our release notes updates, so you always get the best out of Kaltura.
Newsletter