API Outputs | Clarifai Docs
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"
}
}
}
Response Sections
Typically, an API 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).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.