## 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: value` syntax 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 ```json { "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 ```text 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 `id` is 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: ```text status { code: SUCCESS description: "Ok" req_id: "a6073f6b81df496faa084355a05f81f0" } ``` Below is an example of a successful response from a REST API request: ```text "status": { "code": 10000, "description": "Ok", "req_id": "20ab5bcf0566429f9b350e50372456ce" } ``` Below is an example of a failed response from a gRPC API request: ```text 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: ```text "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.