Introduction

Backprop's API is used to do model inference via a task interface and manage models.

You can interact with the API via HTTP, using your preferred client. If using Python, it is easiest to use our library.

Backprop's API contains general purpose natural language and vision tasks that are implemented by curated state-of-the-art models. See an overview of these models in the Model Hub.

Your own uploaded models behave the same way, except they are private and can support the custom task which lets you pass any parameters.

Authentication

Every request must be authenticated by including your API key in the x-api-key header. Your API key is a secret and should not be shared. If you accidentally share it, then cycle it via settings.

Tasks

Tasks are model interfaces. They ensure that you can use a large variety of models without having to customise your requests on a per model basis.

Every task takes a model field in the request body.

Learn more about tasks in the tasks tutorial.

Question answering

Performs question answering via context. The model predicts the likeliest answer to your question.

Perform QA

POST https://api.backprop.co/qa

Does question answering using provided parameters and model.

Request body


model string Optional Defaults to english-base

Model identifier of a qa model. See available qa models in Hub.

question string or array Required

The question to ask on the context. Can be a string or list of strings (if also providing multiple contexts).

context string or array Required

The context to ask the question from. Can be a string or list of strings (if also providing multiple questions).

prev_q array or arrays Optional

Previous questions that have been asked (for conversational models). Can be a array of questions or array of question arrays (if providing multiple questions and contexts).

prev_a array or arrays Optional

Answers to previous questions (for conversational models). Can be a array of answers or array of answer arrays (if providing multiple questions and contexts). Must match prev_q.

Aliases


english-base default
t5-base-qa-summary-emotion
Copy
curl https://api.backprop.co/qa \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "question": "What animal has nine lives?",
  "context": "According to scientists, cats have nine lives.",
  "model": "english-base"
}'
      
Copy
{
  "answer": "cat"
}

Text classification

Classifies text in a zero-shot manner or using pre-trained labels. If using a zero-shot model, labels must be provided.

Perform text classification

POST https://api.backprop.co/text-classification

Calculates probabilities for text, given labels.

Request body


model string Optional Defaults to english-base

The text classification model identifier. See available text classification models in Hub. For zero-shot models, each label has a probability between 0 and 1.

text string or array Required

Text or array of texts to classify. Each text can be up to the model'smax text length (in tokens) in size. Anything over that will be truncated.

labels array or arrays Optional

Array of labels to predict probabilities for. Only zero-shot models support this field.

top_k integer Optional

Number of highest probability labels to return. If set to 5, only returns top 5 most probable labels.
0 is a special value where all labels are returned.

Aliases


english-base default
deberta-base-mnli

english-large
bart-large-mnli

multilingual-large
xlmr-large-xnli
Copy
curl https://api.backprop.co/text-classification \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "My product broke.",
  "labels": [
    "shipping",
    "product issue"
  ],
  "model": "english-base"
}'
      
Copy
{
  "probabilities": {
    "product issue": 0.85,
    "shipping": 0.1
  }
}

Image classification

Classifies images in a zero-shot manner or using pre-trained labels. If using a zero-shot model, labels must be provided.

Perform image classification

POST https://api.backprop.co/image-classification

Calculates probabilities for an image, given labels.

Request body


model string Optional Defaults to english-base

The image classification model identifier. See available image classification models in Hub. For zero-shot models, each label has a probability between 0 and 1.

image string or array Required

Image or array of images to classify. The image must be a base64encoded string.

labels array or arrays Optional

Array of labels to predict probabilities for. Only zero-shot models support this field.

top_k integer Optional

Number of highest probability labels to return. If set to 5, only returns top 5 most probable labels.
0 is a special value where all labels are returned.

Aliases


english-base default
clip
Copy
curl https://api.backprop.co/image-classification \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "image": "base64EncodedImage",
  "labels": [
    "cat",
    "dog"
  ],
  "model": "english-base"
}'
      
Copy
{
  "probabilities": {
    "dog": 0.957,
    "cat": 0.043
  }
}

Text summarisation

Get the "tldr" of a long body of text.

Perform summarisation

POST https://api.backprop.co/summarisation

Creates a summary of provided text.

Request body


model string Optional Defaults to english-base

The summarisation model identifier. See available summarisation models in Hub.

text string or array Required

Text or array of text to summarise.
Each text can be up to the model's max text length (in tokens) in size. Anything over that will be truncated.

Aliases


english-base default
t5-base-qa-summary-emotion

english-small
t5-small
Copy
curl https://api.backprop.co/summarisation \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "Text to summarise",
  "model": "english-base"
}'
      
Copy
{
  "summary": "Summary of long text."
}

Text generation

Generates text, given some base text and generation specific parameters.

Perform text generation

POST https://api.backprop.co/text-generation

Uses a language model to continue generating text from your input text. Used to solve a large variety of tasks, given the right model.

The total input and output text can't exceed the model's max text length (in tokens).

Request body


model string Optional Defaults to english-base

The text generation model identifier. See available text generation models in Hub.

min_length integer Optional Defaults to 10

Minimum number of tokens to generate. Each token is roughly 1 word.

max_length integer Optional Defaults to 20

Maximum number of tokens to generate. Each token is roughly 1 word.

temperature float Optional

Value that alters the randomness of generation.0.0 is no randomness, higher values introduce randomness.

0.5 is a good starting point.


top_k integer Optional

Only choose from the top k highest probability tokens when generating.
0 is a special value where all tokens are considered.

top_p float Optional

Value between 0 and 1 that determines the top tokens with a combined probability of top_p to choose from.

repetition_penalty float Optional

Penalty to be applied to tokens present in the provided text and tokens already generated in the sequence (>1 discourages repetition while <1 encourages).

length_penalty float Optional

Penalty applied to overall text length. Set >1 for longer text, or <1 for shorter ones.

num_beams integer Optional Defaults to 1

Does num_beams number of generations server side to pick the best one.

Note: Higher values use a lot of computation.


num_generations integer Optional Defaults to 1

Does num_beams number of generations and returns all as an array.

Note: Higher values use a lot of computation.

Aliases


english-small
distilgpt2

english-base default
gpt2-medium

english-large
gpt2-large
Copy
curl https://api.backprop.co/text-generation \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "Once upon a time",
  "max_length": 30,
  "temperature": 0.5,
  "model": "english-base"
}'
      
Copy
{
  "output": ", I thought it might be possible to see the world through a lens of my own creation to better"
}

Emotion detection

Analyse text for sentiment.

Perform emotion

POST https://api.backprop.co/emotion

Detects emotion from provided text. Returns a string of comma separated emotions.

Request body


model string Optional Defaults to english-base

The emotion model identifier. See available emotion models in Hub.

text string or array Required

Text or array of text to detect emotion from.
Each text can be up to the model's max text length (in tokens) in size. Anything over that will be truncated.

Aliases


english-base default
t5-base-qa-summary-emotion
Copy
curl https://api.backprop.co/emotion \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "I have been pretty ecstatic since I got that mango for christmas.",
  "model": "english-base"
}'
      
Copy
{
  "emotion": "excitement"
}

Text vectorisation

Get a vector representation of text from the model's internal state. Allows comparing text using mathematical functions like cosine similarity.

Perform text vectorisation

POST https://api.backprop.co/text-vectorisation

Turns the provided text into a vector. The vector's size is determined by the model's vector size.

Vectors should not be mixed and matched between models.

Request body


model string Optional Defaults to msmarco-distilroberta-base-v2

The text vectorisation model identifier. See available text vectorisation models in Hub.

text string or array Required

Text or array of text to vectorise.
Each text can be up to the model's max text length (in tokens) in size. Anything over that will be truncated.
Copy
curl https://api.backprop.co/text-vectorisation \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "Text to vectorise",
  "model": "msmarco-distilroberta-base-v2"
}'
      
Copy
{
  "vector": [0.231241, -0.821311, ...]
}

Image vectorisation

Get a vector representation of an image from the model's internal state. Allows comparing images using mathematical functions like cosine similarity.

Perform image vectorisation

POST https://api.backprop.co/image-vectorisation

Turns the provided image into a vector. The vector's size is determined by the model's vector size.

Vectors should not be mixed and matched between models.

Request body


model string Optional Defaults to clip

The image vectorisation model identifier. See available image vectorisation models in Hub.

image string or array Required

Image or array of images to vectorise.
The image must be a base64 encoded string.
Copy
curl https://api.backprop.co/image-vectorisation \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "image": "base64EncodedImage",
  "model": "clip"
}'
      
Copy
{
  "vector": [0.231241, -0.821311, ...]
}

Image-text vectorisation

Get a combined vector representation of an image and text from the model's internal state. Allows comparing image and text pairs using mathematical functions like cosine similarity.

Perform image-text vectorisation

POST https://api.backprop.co/image-text-vectorisation

Turns the provided image and text into a vector. The vector's size is determined by the model's vector size.

Vectors should not be mixed and matched between models.

Request body


model string Optional Defaults to clip

The image-text vectorisation model identifier. See available image-text vectorisation models in Hub.

image string or array Required

Image or array of images to vectorise.
The image must be a base64 encoded string.

text string or array Required

Text or array of text to vectorise.
Each text can be up to the model's max text length (in tokens) in size. Anything over that will be truncated.
Copy
curl https://api.backprop.co/image-text-vectorisation \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
  "image": "base64EncodedImage",
  "text": "two happy monkeys",
  "model": "clip"
}'
      
Copy
{
  "vector": [0.231241, -0.821311, ...]
}

Custom

Endpoint to perform a custom, user defined task.

Perform custom

POST https://api.backprop.co/custom

Calls a model's custom task. The endpoint can take any parameters via the request body.

None of the global models implement this task, so only custom uploaded models can be used with this.

Request body


model string Required

The name of your custom model.
Copy
curl https://api.backprop.co/custom \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "my-model",
 "my_field": [9, 1, 0]
}'
Copy
{
  "output": [0, 2, 5]
}

Models

Models power tasks. They follow the task's interface to turn provided input into appropriate output.

Using the API, it is possible to view available global models and upload/delete your own.

List models

GET https://api.backprop.co/models

Gets a list of global and user uploaded models. Some info about global models is not shown.

Query parameters


include_global boolean Optional Defaults to true

Whether to include global models in the response.
Copy
curl https://api.backprop.co/models \
 -H "x-api-key: YOUR_API_KEY_HERE"
Copy
[
  {
    "id": "model_bart-large-mnli",
    "name": "bart-large-mnli",
    "description": "Large version of Facebook AI's BART, finetuned on the Multi-Genre Natural Language Inference dataset for zero-shot text classification.",
    "tasks": [
      "text-classification"
    ],
    "details": {
      "credits": [
        {
          "name": "Facebook AI",
          "url": "https://arxiv.org/abs/1910.13461"
        },
        {
          "name": "Hugging Face",
          "url": "https://huggingface.co/transformers/model_doc/bart.html"
        }
      ],
      "max_text_length": 1024,
      "num_parameters": 407344131,
      "text-classification": {
        "languages": [
          "eng"
        ],
        "score": {
          "description": "Matched accuracy of 89.9% and mismatched accuracy of 90.01% on the MNLI test set.",
          "value": 4
        },
        "zero_shot": true
      }
    },
    "build_status": "success",
    "last_deployment": "2021-04-15T11:27:17Z"
  }
]

Get model details

GET https://api.backprop.co/models/:model

Gets details about a specific model by its identifier. Some info about global models is not shown.

Returns 404 if the model is not found or you do not have permissions to view the model.

Path parameters


model string Required

The name of the model to get details for.
Copy
curl https://api.backprop.co/models/pytorch-example \
 -H "x-api-key: YOUR_API_KEY_HERE"
Copy
{
  "id": "model_pytorch-example",
  "name": "pytorch-example",
  "description": "This is an example PyTorch model.",
  "tasks": [
    "text-classification",
    "text-vectorisation",
    "custom"
  ],
  "details": null,
  "last_deployment": "2021-03-31T13:23:32Z",
  "build_status": "success",
  "build_message": "",
  "model_url": "https://kiri-user-models.s3.eu-central-1.amazonaws.com/...",
  "config_url": "https://kiri-user-models.s3.eu-central-1.amazonaws.com/...",
  "requirements_url": "https://kiri-user-models.s3.eu-central-1.amazonaws.com/..."
}

Get model upload URL

POST https://api.backprop.co/upload-url

Gets an upload url for a model. The upload url is valid for an hour and takes a PUT request with a zip file.

To learn more, check out the deploying tutorial.

Request body


model_name string Required

The name of the model to upload. If using the name of the existing model, a new deployment of it will be made.
Must be between 3-100 characters. Lowercase ascii with numbers, dashes (-) and underscores (_).
Using the same name as a global model will override it for you.
Copy
curl https://api.backprop.co/upload-url \
 -H "x-api-key: YOUR_API_KEY_HERE" \
 -d {"model_name": "some-model"}
Copy
https://kiri-user-uploads.s3.eu-central-1.amazonaws.com/acc_id/some-model.zip

Delete model

DELETE https://api.backprop.co/models/:model

Permanently deletes a model.

Returns 404 if the model is not found or you do not have permissions to delete the model.

Path parameters


model string Required

The name of the model to delete.
Copy
curl https://api.backprop.co/model/pytorch-example \
 --request DELETE \
 -H "x-api-key: YOUR_API_KEY_HERE"
Copy
""