The ML Clever Prediction API provides a powerful way to integrate predictions from your trained models directly into your own applications, services, or automated workflows. Instead of using the platform's UI, you can programmatically send input data and receive prediction results via a simple HTTP POST request.
This enables seamless integration for real-time scoring within web applications, automating decisions in backend processes, enriching data pipelines, or building custom tools that leverage your machine learning models. The API is designed for speed and scalability, utilizing caching mechanisms for optimal performance.
To use the Prediction API, you first need an API Key. Each API key is linked to a specific **Model Deployment**. Deploying a model makes it accessible via the API and generates a unique key for authentication.
API Keys are generated when you create a Model Deployment within the ML Clever platform. You will need to navigate to the model you wish to use and create an active deployment for it.
Learn how to Create Model DeploymentsTreat your API keys like passwords – keep them secure and do not expose them in client-side code or public repositories.
Once you have an active deployment and its API key, you can make predictions by sending an HTTP POST request to the API endpoint.
Method: POST
URL: https://app.mlclever.com/api/predict/<key>
Content-Type: application/json
The body of your POST request must be a JSON object containing the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| api_key | String | Yes | Your unique API key obtained from an active Model Deployment. |
| input_data | Object | Yes | A JSON object where keys are the exact feature names the model expects, and values are the corresponding input values. Data types must match those expected by the model (e.g., strings for text/categories, numbers for numerical features). |
input_data object. Missing features will result in an error (See Error Responses).
curl -X POST https://your-ml-clever-instance.com/api/predict \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"input_data": {
"feature1_name": "value1",
"feature2_name": 123.45,
"categorical_feature": "category_A"
}
}'
import requests
import json
api_url = "https://your-ml-clever-instance.com/api/predict"
api_key = "YOUR_API_KEY" # Keep your API key secure!
input_payload = {
"api_key": api_key,
"input_data": {
"feature1_name": "value1",
"feature2_name": 123.45,
"categorical_feature": "category_A"
# Add all required features for your model
}
}
headers = {
"Content-Type": "application/json"
}
try:
response = requests.post(api_url, headers=headers, data=json.dumps(input_payload))
response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
prediction_data = response.json()
print("Prediction successful:")
print(prediction_data)
except requests.exceptions.RequestException as e:
print(f"API request failed: {e}")
if response is not None:
try:
print(f"Error details: {response.json()}")
except json.JSONDecodeError:
print(f"Error details: {response.text}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
The API will respond with a JSON object indicating success or failure.
If the request is successful, the response body will contain:
| Field | Type | Description |
|---|---|---|
| predictions | List | A list containing the prediction result(s). For classification, this might be the predicted class label. For regression, it's the predicted numerical value (rounded to 2 decimal places if numeric). Multi-output models may return multiple items. |
| confidence_intervals | List (Optional) | For classification models, this may contain a list of probabilities corresponding to each class label, indicating the model's confidence. |
{
"predictions": [
"PredictedClassA",
0.85
],
"confidence_intervals": [
0.95,
0.85,
0.10
]
}
If an error occurs, the response body will contain an error field describing the issue. Sometimes additional fields like missing_columns are included.
{
"error": "Prediction failed due to missing input data",
"missing_columns": [
"feature3_name",
"feature4_name"
]
}
{
"error": "Invalid API key"
}
200 OK: Success.400 Bad Request: Invalid request format, missing required fields (like input_data), invalid input data types, or missing feature columns in input_data. The `error` message provides specifics.401 Unauthorized: Invalid or missing `api_key`.403 Forbidden: The API key is valid, but the associated Model Deployment is not `active`.404 Not Found: The model associated with the API key could not be found (rare, indicates an issue with the deployment).429 Too Many Requests: You have exceeded the rate limits.500 Internal Server Error: An unexpected error occurred on the server side. Check logs or contact support if persistent.To ensure fair usage and stability, the Prediction API enforces rate limits based on the source IP address. Exceeding these limits will result in an HTTP 429 Too Many Requests error.
1,000,000 requests10,000,000 requestsIf you anticipate needing higher limits, please contact support.
The API backend utilizes caching (via Redis) to optimize performance for frequently accessed models and their associated metadata (like required columns).
When a prediction request comes in:
This caching is handled automatically on the server-side to ensure low latency for your prediction requests.
The Prediction API unlocks numerous possibilities for leveraging your models:
Integrate predictions directly into user-facing web or mobile apps (e.g., predict loan eligibility, recommend products, estimate delivery times based on user input).
Automate decisions within backend systems (e.g., flag fraudulent transactions, route customer support tickets, prioritize leads based on predicted value).
Add model predictions as new features to datasets in your data warehouse or ETL processes.
Direct traffic to different deployed model versions via their respective API keys to compare performance in live environments.
Create internal dashboards or tools that allow non-technical users to get predictions without directly accessing the ML platform.
Treat API keys as sensitive credentials. Store them securely (e.g., environment variables, secrets management systems). Do not embed them directly in source code, especially client-side applications.
Your application should gracefully handle potential API errors (4xx, 5xx status codes, network issues). Check the response status code and the `error` message in the JSON body. Implement retry logic with backoff for transient errors (like 500 or network timeouts).
Ensure the input_data object sent to the API contains all required features with the correct names and data types expected by the model. Mismatches will lead to 400 errors.
Design your application to stay within the specified rate limits. If processing large volumes, consider batching requests on your end or using the platform's Batch Prediction feature if applicable.
To effectively use the API, understand these related areas:
Learn how to deploy your trained models to make them accessible via the API and generate API keys.
Manage DeploymentsExplore the UI-based method for making single predictions interactively.
Use the Real-Time UILearn how to process entire datasets for predictions using the platform's UI.
Explore Batch Processing