Run a job using REST API

To successfully run a job in aiWARE, you must first get a token. Then, using the REST API, you can create the job, poll the job's status, and get the job's results.

Before you begin

To access any aiWARE API, you must first Get a token.

Steps

1. (Optional) Select an engine. If you don't already know the engines you want to use as part of your job, you can get all available engines and review them.

   To get a list of all engines, use the AI Processing REST API by making a GET request to /admin/engines. This returns a list of the available engines on a given instance of AI Processing.

   The response is a JSON array that includes three key-value pairs:

   • The category ID of the engine(transcription, translation, etc.)

     "engineCategoryID": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

   • The engine ID that will be used to create the job

     "engineID": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

   • The name of the engine

     "engineName": "string"

2. Create the job.

   You can create a job on a hosted instance of AI Processing by sending a POST request to /proc/job/create. Below is a sample curl command:

   curl --request POST \
    --url http://localhost:9000/edge/v1/proc/job/create \
    --header 'authorization: Bearer <_YOUR_TOKEN_HERE>' \
    --header 'content-type: application/json' \
    --data '<the JSON shown below, starting with { "jobs" '

   Below is a sample JSON data payload for a translation job:

   {
    "jobs": [
   {
     "dueDateTime": "2020-02-18T20:49:18.331Z",
     "tasks": [
       {
         "correlationTaskId": "__TRANSLATION_TASK_ID_UUID__",
         "dueDateTime": "2020-02-18T20:49:18.331Z",
         "engineId": "95c910f6-4a26-4b66-96cb-488befa86466",
         "ioFolders": [
           {
             "correlationID": "__TRANSLATION_TASK_OUTPUT_ID_UUID__",
             "mode": "chunk",
             "optionsJSON": "{}",
             "type": "output"
           }
         ],
         "maxEngines": 1,
         "maxRetries": 10,
         "payloadJSON": "{\"url\":\"https://vt-maxagg-test.s3.amazonaws.com/media/spanish.txt\"}",
         "taskPayloadJSON": "{\"url\":\"https://vt-maxagg-test.s3.amazonaws.com/media/spanish.txt\"}",
         "taskStatus": "pending",
         "priority": -10
       },
       {
         "correlationTaskId": "__OUTPUT_WRITER_TASK_ID_UUID__",
         "dueDateTime": "2020-02-14T20:49:18.331Z",
         "engineId": "8eccf9cc-6b6d-4d7d-8cb3-7ebf4950c5f3",
         "ioFolders": [
           {
             "correlationID": "__OUTPUT_WRITER_TASK_INPUT_ID_UUID__",
             "mode": "chunk",
             "optionsJSON": "{}",
             "type": "input"
           }
         ],
         "maxEngines": 1,
         "maxRetries": 10,
         "payloadJSON": "{}",
         "taskPayloadJSON": "{}",
         "taskStatus": "pending"
       }
     ],
     "taskRoutes": [
       {
         "taskChildId": "__TRANSLATION_TASK_ID_UUID__"
       },
       {
         "taskParentId": "__TRANSLATION_TASK_ID_UUID__",
         "taskParentOutputId": "__TRANSLATION_TASK_OUTPUT_ID_UUID__",
         "taskChildId": "__OUTPUT_WRITER_TASK_ID_UUID__",
         "taskChildInputId": "__OUTPUT_WRITER_TASK_INPUT_ID_UUID__"
       }
     ]
   }
    ]
   }

   The input file is not uploaded but is specified via a URL (in a serialized payload object). The fields containing "UUID___" must include a unique identifier in the form of a UUID. You can use any UUID-generation library to generate these values.

3. Poll the job for status.

   You can review the status of the job you created by polling it for status. The possible statuses of a job are:

   • Pending - The job definition has been validated, the job is created, and it's waiting to be picked up from an AI Processing node.
   • Complete - The job is complete and the job results are now available.
   • Running - The job is currently in progress and has at least one task being executed.
   • Canceled - The job has been canceled and will not be completed. SeeCanceling jobs for more information.
   • Queued - The job has been selected by an AI Processing node and is awaiting available resources for execution.
   • Failed - An error occurred and the job has failed. Errors occur at the individual task level, but you can retry the failed job once any error has been addressed.

   You can poll a job status by sending a GET request to /proc/job/<_YOUR_JOB_ID>/outputs with the InternalJobId. You can periodically make GET requests until a JSON file is returned in the name key of the outputs array of the API response:

   {
    "outputs": {
    "internalJobID": "e1484460-7cb5-4cab-87ea-436c4768904f",
   "outputs": [
      {
        "created": 1581102672,
        "name": "vtn-standard-489cbc5b-b6b0-43d5-8b12-e790865986b5.json",
        "size": 4344
      }
    ]
     }
   }

4. View the job's results.

   Once the job is completed, you can download the engine results by passing the InternalJobId and name from when you polled the job's status, as shown in the curl sample below.

   curl --request GET \
    --url http://localhost:9000/edge/v1/proc/job/<job id here>/output/<file name here>.json \
    --header 'authorization: Bearer <_TOKEN_>'

• To delete a TDO when it is no longer required, see Delete a TDO and/or its content.
• To cancel or retry a job, see Manage jobs using the API.
• To learn in-depth how jobs are processed in aiWARE, see Job processing.
• For details about the functions of jobs, tasks, and TDOs, see Jobs, tasks, and TDOs.
• For documentation of the methods in the AI Processing API, see Veritone aiWARE Edge API.