API Outputs
Understand Clarifai’s API responses
Clarifai’s API responses are designed to provide clear and structured feedback to help you easily interpret results and effectively debug your code. Each API response adheres to a well-defined, nested, hierarchical structure, where data is organized into distinct messages and fields.
The responses are delivered in different data formats depending on your request, but they can be processed in a similar manner programmatically.
-
REST API requests deliver responses in JSON, characterized by the
{ "key": "value" }syntax. -
For gRPC requests, typically made through our Python SDK or other client libraries, responses are provided in Protocol Buffers (protobuf), a binary serialization format optimized for speed and size. Protobuf uses the
key: valuesyntax in its text format.
The specific content within a response varies based on the API endpoint you've used. For example, a response from a model prediction request will differ significantly from one obtained when creating a concept.
Example response from REST API request
{
"status": {
"code": 10000,
"description": "Ok",
"req_id": "20ab5bcf0566429f9b350e50372456ce"
},
"outputs": [{
"id": "a03a4b326e3041e88983a88b58c41f2b",
"status": {
"code": 10000,
"description": "Ok"
},
"created_at": "2025-02-28T09:41:55.568082659Z",
"model": {
"id": "general-image-recognition",
"name": "Image Recognition",
"created_at": "2016-03-09T17:11:39.608845Z",
"modified_at": "2025-02-18T17:49:04.809517Z",
"app_id": "main",
"model_version": {
"id": "aa7f35c01e0642fda5cf400f543e7c40",
"created_at": "2018-03-06T21:10:24.454834Z",
"status": {
"code": 21100,
"description": "Model is trained and ready for deployment"
},
"visibility": {
"gettable": 50
},
"app_id": "main",
"user_id": "clarifai",
"metadata": {}
},
"user_id": "clarifai",
"model_type_id": "visual-classifier",
"visibility": {
"gettable": 50
},
"toolkits": [],
"use_cases": [],
"languages": [],
"languages_full": [],
"check_consents": [],
"workflow_recommended": false,
"image": {
"url": "https://data.clarifai.com/large/users/clarifai/apps/main/input_owners/artjom/inputs/image/3451432d5ee13c416ec5a4e8e518f1c9",
"hosted": {
"prefix": "https://data.clarifai.com",
"suffix": "users/clarifai/apps/main/input_owners/artjom/inputs/image/3451432d5ee13c416ec5a4e8e518f1c9",
"sizes": ["small", "large"],
"crossorigin": "use-credentials"
}
}
},
"input": {
"id": "6f341a82f6bb4326ab637e590b654a57",
"data": {
"image": {
"url": "https://samples.clarifai.com/metro-north.jpg",
"base64": "dHJ1ZQ=="
}
}
},
"data": {
"concepts": [{
"id": "ai_HLmqFqBf",
"name": "train",
"value": 0.99960595,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_fvlBqXZR",
"name": "railway",
"value": 0.99929917,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_SHNDcmJ3",
"name": "subway system",
"value": 0.9982582,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_6kTjGfF6",
"name": "station",
"value": 0.99801373,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_RRXLczch",
"name": "locomotive",
"value": 0.9972677,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_Xxjc3MhT",
"name": "transportation system",
"value": 0.996977,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_VRmbGVWh",
"name": "travel",
"value": 0.98897153,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_jlb9q33b",
"name": "commuter",
"value": 0.9808896,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_2gkfMDsM",
"name": "platform",
"value": 0.98066735,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_n9vjC1jB",
"name": "light",
"value": 0.9742649,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_sQQj52KZ",
"name": "train station",
"value": 0.968873,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_l4WckcJN",
"name": "blur",
"value": 0.96725816,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_WBQfVV0p",
"name": "city",
"value": 0.96156096,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_TZ3C79C6",
"name": "road",
"value": 0.96141803,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_CpFBRWzD",
"name": "urban",
"value": 0.96043277,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_tr0MBp64",
"name": "traffic",
"value": 0.95991284,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_GjVpxXrs",
"name": "street",
"value": 0.94766,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_mcSHVRfS",
"name": "public",
"value": 0.9343276,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_J6d1kV8t",
"name": "tramway",
"value": 0.9321725,
"app_id": "main",
"user_id": "clarifai"
}, {
"id": "ai_6lhccv44",
"name": "business",
"value": 0.9293912,
"app_id": "main",
"user_id": "clarifai"
}]
}
}]
}
Example response from gRPC API request
status {
code: SUCCESS
description: "Ok"
req_id: "a6073f6b81df496faa084355a05f81f0"
}
outputs {
id: "515a810bb56b4ac1bb118fe7ec4594be"
status {
code: SUCCESS
description: "Ok"
}
created_at {
seconds: 1740731206
nanos: 185089857
}
model {
id: "general-image-recognition"
name: "Image Recognition"
created_at {
seconds: 1457543499
nanos: 608845000
}
modified_at {
seconds: 1739900944
nanos: 809517000
}
app_id: "main"
model_version {
id: "aa7f35c01e0642fda5cf400f543e7c40"
created_at {
seconds: 1520370624
nanos: 454834000
}
status {
code: MODEL_TRAINED
description: "Model is trained and ready for deployment"
}
visibility {
gettable: PUBLIC
}
app_id: "main"
user_id: "clarifai"
metadata {
}
}
user_id: "clarifai"
model_type_id: "visual-classifier"
visibility {
gettable: PUBLIC
}
workflow_recommended {
}
image {
url: "https://data.clarifai.com/large/users/clarifai/apps/main/input_owners/artjom/inputs/image/3451432d5ee13c416ec5a4e8e518f1c9"
hosted {
prefix: "https://data.clarifai.com"
suffix: "users/clarifai/apps/main/input_owners/artjom/inputs/image/3451432d5ee13c416ec5a4e8e518f1c9"
sizes: "small"
sizes: "large"
crossorigin: "use-credentials"
}
}
}
input {
id: "ac7bc26bc08444ca894bff202e28801a"
data {
image {
url: "https://samples.clarifai.com/metro-north.jpg"
base64: "true"
}
}
}
data {
concepts {
id: "ai_HLmqFqBf"
name: "train"
value: 0.999605954
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_fvlBqXZR"
name: "railway"
value: 0.999299169
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_SHNDcmJ3"
name: "subway system"
value: 0.998259127
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_6kTjGfF6"
name: "station"
value: 0.998013735
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_RRXLczch"
name: "locomotive"
value: 0.997266769
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_Xxjc3MhT"
name: "transportation system"
value: 0.996975541
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_VRmbGVWh"
name: "travel"
value: 0.988967478
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_jlb9q33b"
name: "commuter"
value: 0.980903447
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_2gkfMDsM"
name: "platform"
value: 0.980670214
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_n9vjC1jB"
name: "light"
value: 0.974255323
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_sQQj52KZ"
name: "train station"
value: 0.968879461
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_l4WckcJN"
name: "blur"
value: 0.967263579
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_WBQfVV0p"
name: "city"
value: 0.961552262
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_TZ3C79C6"
name: "road"
value: 0.961399674
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_CpFBRWzD"
name: "urban"
value: 0.960412741
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_tr0MBp64"
name: "traffic"
value: 0.959924757
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_GjVpxXrs"
name: "street"
value: 0.947632849
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_mcSHVRfS"
name: "public"
value: 0.934372783
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_J6d1kV8t"
name: "tramway"
value: 0.932164907
app_id: "main"
user_id: "clarifai"
}
concepts {
id: "ai_6lhccv44"
name: "business"
value: 0.929403365
app_id: "main"
user_id: "clarifai"
}
}
}
Typically, the response consists of several key sections, including:
- Id — The
idis a unique identifier assigned to an API operation or resource. It serves as a reference that allows tracking, retrieval, and management of the request or resource in future interactions. Example:id: "a6fbf0c4f4bf4bb09f2158ad3f8dfc4e". - Status — Indicates the overall success or failure of the request.
- Outputs — Contains details about the data processed by the API (such as images, videos, or text) and the results of the analysis, such as timestamps, resource information, and other relevant details.
- Results — This section, which is mostly found within the outputs section, contains the core results of the API call, such as predictions or analysis data.
Status Section
The top-level status section provides information about the outcome of the API request. It includes:
code— A numeric or string code indicating the status (such as 10000 or SUCCESS for a successful response). See a list of all the Clarifai’s status codes here.description— A human-readable message describing the status (such as "Ok", "Download pending").req_id— A unique identifier for the request, useful for debugging and tracking.
Below is an example of a successful response from a gRPC API request:
status {
code: SUCCESS
description: "Ok"
req_id: "a6073f6b81df496faa084355a05f81f0"
}
Below is an example of a successful response from a REST API request:
"status": {
"code": 10000,
"description": "Ok",
"req_id": "20ab5bcf0566429f9b350e50372456ce"
},
Below is an example of a failed response from a gRPC API request:
code: MODEL_DOES_NOT_EXIST
description: "Model does not exist"
details: "Model does not exist"
req_id: "4d6cf25f4e0c48b19ff3ec1755ac1b29"
Below is an example of a failed response from a REST API request:
"status": {
"code": 21200,
"description": "Model does not exist",
"details": "Model does not exist",
"req_id": "09715165a0d24a109f3951b61d73dfe8"
}
Outputs Section
Beyond the status output, the content of the response varies depending on the type of operation you performed.
Below are some of the most common details found in API responses.
Resource Details
The response can include details about the resource involved in the request, such as an input, model, workflow, or application.
For example, when analyzing an image input, you can find the id, name, and other relevant details of the model used for processing.
"model": {
"id": "general-image-recognition",
"name": "Image Recognition",
"model_version": {
"id": "aa7f35c01e0642fda5cf400f543e7c40",
"created_at": "2018-03-06T21:10:24.454834Z",
"status": {
"code": 21100,
"description": "Model is trained and ready for deployment"
},
}
}
Timestamps
Timestamps provide important information about when a resource was created and last modified. These timestamps are crucial for tracking changes, auditing, and understanding the lifecycle of resources in your Clarifai projects.
These are the timestamps outputted in a successful response:
created_at— Indicates the exact date and time when a resource or an operation was first created or first performed, respectively.modified_at— Indicates the exact date and time when a resource was last modified.
Below is an example response from a gRPC API request:
The gRPC response includes timestamps in Unix epoch time, which represents the number of seconds since January 1, 1970 (UTC). For example, a created_at field of 1457543499 seconds and 608845000 nanoseconds converts to March 9, 2016, at 10:11:39.608845 AM UTC. The nanos field adds precision by representing fractional seconds.
model {
id: "general-image-recognition",
name: "Image Recognition",
created_at {
seconds: 1457543499,
nanos: 608845000
},
modified_at {
seconds: 1739900944,
nanos: 809517000
},
}
Below is an example response from a REST API request:
In REST API responses, timestamps are converted to the RFC 3339 standard. The standard represents date and time as a string in this format: {year}-{month}-{day}T{hour}:{minute}:{second}[.{fractional_seconds}]Z.
These are the key formatting rules:
- Year (
{year}) is always four digits (such as2025). - Month, day, hour, minute, and second are zero-padded to two digits each (such as
02,09,17). - Fractional seconds (optional) can go up to 9 digits, supporting up to nanosecond resolution (such as
.608845). - The "Z" suffix indicates the UTC time zone (such as
2025-02-18T17:49:04.809517Z).
"model": {
"id": "general-image-recognition",
"name": "Image Recognition",
"created_at": "2016-03-09T17:11:39.608845Z",
"modified_at": "2025-02-18T17:49:04.809517Z",
}
Results Section
When you make a successful API call to Clarifai, the "results" section is where the real action happens. It's the payload containing the information you requested — the insights, predictions, or data derived from your input.
The exact content of the "results" section varies significantly depending on the API endpoint you're using.
Below are some common elements you might encounter across different Clarifai API endpoints (the examples are for REST API requests):
- Image recognition requests — The
outputsfield is a common container for storing the core results of prediction or analysis tasks. Insideoutputs, thedatafield includes the actual results, such as recognizedconcepts(labels) and their confidence scores.
{
"outputs": [
{
"data": {
"concepts": [
{ "id": "dog", "name": "dog", "value": 0.98 },
{ "id": "pet", "name": "pet", "value": 0.95 }
]
}
}
]
}
- Concepts creation requests — The
conceptsfield contains the details of the newly created concept, including its ID, name, and other relevant attributes.
{
"concepts": [
{
"id": "charlie",
"name": "Charlie",
"app_id": "test-app"
}
]
}
- Object detection requests — The
regionsfield contains information about the detected objects within an image or video. This includes bounding box coordinates, associatedconcepts, and their corresponding confidence scores.
{
"outputs": [
{
"data": {
"regions": [
{
"region_info": { "bounding_box": { "top_row": 0.1, "left_col": 0.2, "bottom_row": 0.5, "right_col": 0.6 } },
"data": {
"concepts": [{ "id": "cat", "name": "cat", "value": 0.97 }]
}
}
]
}
}
]
}
- Workflow execution requests — The results contain the outputs of each step in the workflow execution.
{
"results": [
{
"outputs": [
{
"model": { "id": "general-image-recognition" },
"data": {
"concepts": [{ "id": "tree", "name": "tree", "value": 0.92 }]
}
}
]
}
]
}