Overview
This tutorial describes the process to select a model and run inference jobs. It shows how to select a model and a version, write inputs using JSON, submit a job request, check the job’s status, and retrieve the job’s results.
Only Data Scientists, Developers, Auditors, and Projects users can submit jobs visible purchased models with active versions.
Select a model
Browse the model Model Library or call the Library routes to find a model.
Send a request to list models to see a model list:
GET /api/models?author=company&isActive=true&isRecommended=True HTTP/1.1
Host: trial.app.modzy.com
You can also browse models by tags:
GET /api/models/tags/count HTTP/1.1
Host: trial.app.modzy.com
Send a request to retrieve model details with the model identifier to see model details such as the author, latest version, and features:
GET /api/models/c3320c2467 HTTP/1.1
Host: trial.app.modzy.com
Send a request to retrieve version details with the model identifier and version number to see version details such as memory and hardware requirements, input requirements, and version performance:
GET /api/models/c3320c2467/versions/0.0.1 HTTP/1.1
Host: trial.app.modzy.com
Once you selected the model-version to run, make sure you meet its requirements. Here is a checklist to ensure you’re good to go:
- the input types and input file types match the version's input types,
- the input sizes are within the version's input max size,
- the model's memory and hardware requirements are met.
Write inputs in JSON format
Modzy supports several input types such as text, embedded for Base64 strings, aws-s3 for inputs hosted in buckets, and jdbc for inputs stored in databases. Models may accept only some input types. You can always send multiple input items. The input item has a user input name (used to identify results) and contains the model’s input names (required). Below are examples for each input type:
Input type: text
Here, the input item has the user’s input name and contains the model’s required input name and a string of data:
"type":"text",
"sources":{
"provide-any-name": {
"model-input-name": "Place all the text here."
}
}
Input type: embedded
Here, the input item has the user’s input name and contains the model’s required input name and a data URI compatible string:
"type": "embedded",
"sources": {
"provide-any-name": {
"model-input-name": "data:image/jpeg;base64,/..long-data-uri-compatible-string-for-my-image..=="
}
}
Input type: aws-s3
This sample sends both image and text input files to the model. The files are hosted in an AWS S3 bucket. Here, each input item has the user’s input name and contains the model’s required input names and the path to the AWS S3 bucket where the data files are stored.
Use aws-s3-folder to include all the input files in a folder, in this sample all the files in the image_input_folder. Use aws-s3 to include a single file from a folder, in this sample this_text.txt.
# Image files
"type": "aws-s3-folder",
"sources": {
"provide-any-name": {
"model-input-name-1": {
"bucket": "bucket-name",
"key": "image_input_folder"
}
}
}
# Text files
"type": "aws-s3",
"sources": {
"provide-any-name": {
"model-input-name-2": {
"bucket": "bucket-name",
"key": "text_input_folder/this_text.txt"
}
}
}
Input type: jdbc
Here, the input item has the user’s input name and contains the model’s required input name and the details to connect to the database:
{
"provide-any-name": {
"type": "jdbc",
"url": "jdbc:sql://database-server.runajob.com:5432/db",
"username": "user",
"password": "password",
"driver": "org.postgresql.Driver",
"query":"select description as \"model-input-name\" from models.model"
}
}
Submit a job request
To submit a job request, send the inputs, model identifier, and version number to execute. Modzy returns a job identifier, required to check the job’s progress and retrieve results.
Quota limits may block job requests. They define the maximum number of job inputs a user, team, or project can submit within a given date range.
Add the input types, names, file types, and data together with the model identifier and version number and submit the job:
POST /api/jobs HTTP/1.1
Host: trial.app.modzy.com
Authorization: ApiKey apikey.modzy
Content-Type: application/json
Accept: application/json
{
"model":{
"identifier": "ed542963de",
"version": "0.0.27"
},
"input": {
"type": "text",
"sources": {
"happy-text": {
"input.txt": "I love AI! :)"
},
"angry-text": {
"input.txt": "I hate AI! abysmal. adverse. alarming. angry. annoy. anxious :("
},
"mixed": {
"input.txt": "love hate irrational brute"
},
"emojis": {
"input.txt": ":-) :slightly_smiling_face: :disappointed: %%%%%8*"
}
}
}
}
Check the job's status
To find out if the job inference started or finished, check the job’s status:
GET /api/jobs/ff533c7c-3324-4d17-8850-b3c6147c5b5c HTTP/1.1
Host: trial.app.modzy.com
Authorization: ApiKey apikey.modzy
Content-Type: application/json
Get the job's results
Results are returned per input and can be identified with the name provided for each input item upon job request. All the results become available when the job status is updated to Completed.
To get your results, call the get results route with the job identifier:
GET /api/results/ff533c7c-3324-4d17-8850-b3c6147c5b5c HTTP/1.1
Host: trial.app.modzy.com
Authorization: ApiKey apikey.modzy
Content-Type: application/json
Accept: application/json
Jobs requested for multiple input items may have partial results available prior to job completion. Items get fully processed and can be seen in the job details route while the job continues to run.
You can add an input name to the route and filter the results for any given input item:
GET /api/results/ff533c7c-3324-4d17-8850-b3c6147c5b5c/neutral-text/results.json HTTP/1.1
Host: trial.app.modzy.com
Authorization: ApiKey apikey.modzy
Content-Type: application/json