Vision AI API Documentation

About Vision AI
Features and Capabilities
What is asticaVision?

asticaVision API is a general purpose computer vision model with state-of-the-art capabilities. Available through an API, it enables developers to provide users with a powerful and comprehensive suite of image analysis and understanding capabilities.

Try Online

Effortlessly process images and extract valuable insights using the asticaVision API to automate image moderation, automatic categorization, face recognition, and object detection.

The key features of asticaVision API are described below:

1. Face Detection (Age and Gender):
asticaVision API employs advanced facial detection algorithms to accurately identify and analyze faces within images. In addition to detecting the presence of faces, it can also estimate the age and gender of the individuals, providing useful demographic information for targeted marketing or personalized user experiences.

2. Object Detection:
The API is also capable of identifying and detecting a wide range of objects within images, enabling users to ascertain the presence of specific items or elements. This powerful feature can be used for applications such as inventory management, surveillance, and visual search.

3. Image Tagging and Categorization:
asticaVision API uses machine learning techniques to automatically generate descriptive tags and assign appropriate categories to images based on their visual content. This feature simplifies the process of organizing and indexing large image databases, streamlining the search and retrieval of relevant images based on specific keywords or themes.

4. Content Moderation:
The API includes intelligent content moderation capabilities designed to automatically detect and filter out images containing adult content or mature subject matter. This feature significantly reduces the manual effort required to moderate visual content, ensuring that inappropriate material is not displayed on websites, social platforms, or digital applications.

5. Automatic Image Description and Captioning:
Leveraging its advanced computer vision capabilities, asticaVision API can automatically generate descriptive text and captions for images, providing an accurate and concise summary of the visual content. This feature not only helps in enhancing the accessibility of images for visually impaired users but also aids in improving the overall user experience by offering meaningful and contextual information about the images.


The asticaVision API is a powerful and versatile computer vision solution that can be easily integrated into a variety of applications to unlock valuable insights from visual content. Its robust features, including face detection, object detection, image categorization, content moderation, and automatic captioning, make it an ideal choice for those looking to enhance their image analysis and understanding capabilities.

Computer Vision with Javascript SDK
Detect Faces and Objects with Javascript
Using the Javascript SDK

REST API - Making Requests to asticaVision

asticaVision is a computer vision API that allows developers to extract rich metadata from images, and perform computer vision tasks such as object detection. This REST API can be called from any programming language or platform that supports HTTP requests.

Computer Vision Code Samples


Computer Vision Model Inputs

Rest API Overview
  • To use astica API, you need to sign up and obtain an API key from the astica.ai website. The API key will be used to authenticate your requests to the API.
  • The asticaVision REST API has a single endpoint: https://vision.astica.ai/describe
  • The asticaVision API currently supports two different models: version 1.0_full and version 2.0_full.

    Recent 2.1_full model allows the functionality of both models to be used within a single API call, and will prioritize v2.0_full for all overlapping functions.

  • The API accepts a JSON payload that includes the following parameters:
    • tkn (required): your astica API key
    • modelVersion (required): the version of the model you want to use (either 1.0_full or 2.0_full)
    • input (required): HTTPS URL or Base64 encoded string of the image to be analyzed.
    • visionParams (optional): a comma-separated list of options that determine the Vision AI to utilize. Options include description, objects, categories, moderate, tags, brands, color, faces, celebrities, landmarks, gpt, gpt_detailed, describe_all, text_read See All Parameters
    • gpt_prompt (optional): a custom prompt to guide GPT-S caption output. Only used if visionParams includes gpt or gpt_detailed
    • prompt_length (optional): an integer between 4 and 125 representing the ideal number of words to be returned by GPT-S based captions.
    • GPT-S Caption ‐ Custom Prompts:
      API now accepts a customized prompt and preferred output length.

      • This is a natural language prompt allowing creative uses.
      • Use with OCR parameter "text_read" ask questions:
        • Scan packages, invoices, or documents: "Who is this from?"
        • Try "answer the math question" with this image
      • Guide or change the tone of GPT-S caption output
        • "Describe the image in detail and provide the response in Spanish"
        • "Provide your opinion on this piece of artwork"
        • "Explain what is happening in this scene"

Computer Vision with asticaVision API
Parameter List
Computer Vision Capabilities

Vision AI Parameters

Each call to the asticaVision API should include the computer vision parameters that you wish to detect. If you do not supply any parameters, then it will default to all and you will be billed for each transaction for every call.

List of Computer Vision Parameters
  • describe
    Returns a caption which describes the image.
  • describe_all v2.0+ only
    Returns multiple auxilliary captions that describe the image.
  • text_read v2.0+ only
    Returns the results of OCR with positional coordinates.
  • gpt
    Uses the result of asticaVision to create a GPT description. Using this parameter increases the processing time of your API request. Be Patient.
  • gpt_detailed
    Uses the result of asticaVision to create a GPT-4 description. Using this parameter greatly increases the processing time of your API request. Please be patient.
  • faces
    Returns the age and gender of all faces detected in the image.
  • moderate
    Returns a calculated value for different types of sensitive materials found in the image.
  • tags
    Returns a list of descriptive terms which describe the image.
  • brands
    Returns a list of brands that have been identified. For example, a logos on a cup, or a t-shirt.
  • celebrities
    Returns a list of celebrities and other known persons that have been detected in the photo.
  • landmarks
    Returns a list of known locations and landmarks found in the photo. For example, the Eiffel Tower.

Vision AI Output

The API returns a JSON response that includes the following metadata based on provided input parameters

  • caption
    the image caption generated by the GPT model
  • caption_list:
    Additional image captions describing the image
  • caption_tags:
    the image caption generated by the GPT model
  • caption_GPTS:
    GPT-written long-form content description of the image
  • tags:
    a list of tags that describe the image
  • categories:
    a list of general categories describing the image
  • moderate:
    a rating of adult content that was found
  • objects:
    a list of objects detected in the image, along with their coordinates
  • faces:
    a list of faces detected in the image, along with their coordinates and emotions
  • brands:
    a list of brands detected in the image
  • astica:
    the details of this API transactions used
Computer Vision - Curl Command
Computer Vision using CURL
Making Vision AI Requests using Curl

You can submit request to the asticaVision API using CURL.

CURL Sample

The following CURL command can be pasted into a terminal to generate a response from the API. The result will contain the output for each of the parameters that have been specified.

curl --location --request POST 'https://vision.astica.ai/describe' \
--header 'Content-Type: application/json' \
--insecure \
--data '{
  "tkn": "your_api_key",
  "modelVersion": "2.1_full",
  "input": "https://www.astica.org/inputs/analyze_3.jpg",
  "visionParams": "gpt, describe, describe_all, tags, objects",
  "gpt_prompt": "",
  "gpt_length": "90"
}'

Note that you need to replace "YOUR API KEY" with your actual API key.

Vision AI Code Sample
Computer Vision with Python
Detect faces, objects and describe Images using Python

Describe Image ‐ Python Sample Code

This is complete script which demonstrates how to make a request to asticaVision using Python. You can specify the HTTPS URL of the image input, or you can provide a Base64 encoded string. You can uncomment the sample code to send a base64 input.

import requests
import json
import base64
import os
def get_image_base64_encoding(image_path: str) -> str:
    """
    Function to return the base64 string representation of an image
    """
    with open(image_path, 'rb') as file:
        image_data = file.read()
    image_extension = os.path.splitext(image_path)[1]
    base64_encoded = base64.b64encode(image_data).decode('utf-8')
    return f"data:image/{image_extension[1:]};base64,{base64_encoded}"
    
# API configurations
asticaAPI_key = 'YOUR API KEY'  # visit https://astica.ai
asticaAPI_timeout = 25 # in seconds. "gpt" or "gpt_detailed" require increased timeouts
asticaAPI_endpoint = 'https://vision.astica.ai/describe'
asticaAPI_modelVersion = '2.1_full' # '1.0_full', '2.0_full', or '2.1_full'

if 1 == 1:
    asticaAPI_input = 'https://astica.ai/example/asticaVision_sample.jpg' # use https image input (faster)
else:
    asticaAPI_input = get_image_base64_encoding('image.jpg')  # use base64 image input (slower)


# vision parameters:  https://astica.ai/vision/documentation/#parameters
asticaAPI_visionParams = 'gpt,describe,objects,faces'  # comma separated, defaults to "all". 
asticaAPI_gpt_prompt = '' # only used if visionParams includes "gpt" or "gpt_detailed"
asticaAPI_prompt_length = '90' # number of words in GPT response

'''    
    '1.0_full' supported visionParams:
        describe
        objects
        categories
        moderate
        tags
        brands
        color
        faces
        celebrities
        landmarks
        gpt               (Slow)
        gpt_detailed      (Slower)

    '2.0_full' supported visionParams:
        describe
        describe_all
        objects
        tags
        describe_all 
        text_read 
        gpt             (Slow)
        gpt_detailed    (Slower)
        
    '2.1_full' supported visionParams:
        Supports all options 
        
'''

# Define payload dictionary
asticaAPI_payload = {
    'tkn': asticaAPI_key,
    'modelVersion': asticaAPI_modelVersion,
    'visionParams': asticaAPI_visionParams,
    'input': asticaAPI_input,
}



def asticaAPI(endpoint, payload, timeout):
    response = requests.post(endpoint, data=json.dumps(payload), timeout=timeout, headers={ 'Content-Type': 'application/json', })
    if response.status_code == 200:
        return response.json()
    else:
        return {'status': 'error', 'error': 'Failed to connect to the API.'}



# call API function and store result
asticaAPI_result = asticaAPI(asticaAPI_endpoint, asticaAPI_payload, asticaAPI_timeout)

# print API output
print('\nastica API Output:')
print(json.dumps(asticaAPI_result, indent=4))
print('=================')
print('=================')
# Handle asticaAPI response
if 'status' in asticaAPI_result:
    # Output Error if exists
    if asticaAPI_result['status'] == 'error':
        print('Output:\n', asticaAPI_result['error'])
    # Output Success if exists
    if asticaAPI_result['status'] == 'success':
        if 'caption_GPTS' in asticaAPI_result and asticaAPI_result['caption_GPTS'] != '':
            print('=================')
            print('GPT Caption:', asticaAPI_result['caption_GPTS'])
        if 'caption' in asticaAPI_result and asticaAPI_result['caption']['text'] != '':
            print('=================')
            print('Caption:', asticaAPI_result['caption']['text'])
        if 'CaptionDetailed' in asticaAPI_result and asticaAPI_result['CaptionDetailed']['text'] != '':
            print('=================')
            print('CaptionDetailed:', asticaAPI_result['CaptionDetailed']['text'])
        if 'objects' in asticaAPI_result:
            print('=================')
            print('Objects:', asticaAPI_result['objects'])
else:
    print('Invalid response')
Vision AI Code Sample
Computer Vision with PHP
Object Detection and Facial Recognition using PHP

You can implement computer vision capabilities by using PHP CURL.

Using PHP to Detect Objects - Sample Code

This example demonstrates how to make perform computer vision using PHP. Like with other languages, you can send an input as either HTTPS URL or a base64 encoded string. The $asticaAPI_visionParams variable an be modified with the desired parameters to specify exact computer vision capabilities, or 'all' can be used to generate all outputs.

<?php    
    $asticaAPI_key = '26d7e90d0b2090b30b3ss21ls1ss'; //visit https://astica.ai
    $asticaAPI_timeout = 60; // seconds  Using "gpt" or "gpt_detailed" will increase response time.

    $asticaAPI_endpoint = 'https://vision.astica.ai/describe';
    $asticaAPI_modelVersion = '2.1_full';  //1.0_full or 2.0_full  

    //Input Method 1: https URL of a jpg/png image (faster)
    $asticaAPI_input = 'https://astica.ai/example/asticaVision_sample.jpg'; 
    
    /*
    //Input Method 2: base64 encoded string of a local image (slower)  
    $image_path = 'image.jpg';
    $image_data = file_get_contents($image_path);
    $image_extension = pathinfo($image_path, PATHINFO_EXTENSION);
    $asticaAPI_input = 'data:image/' . $image_extension . ';base64,' . base64_encode($image_data);
    */
    
    //comma separated options; leave blank for all; note "gpt" and "gpt_detailed" are slower.
    //see all: https://astica.ai/vision/documentation/#parameters
    $asticaAPI_visionParams = 'gpt, describe, describe_all, tags, objects, faces'; 
    $asticaAPI_gpt_prompt = ''; // only used if visionParams includes "gpt" or "gpt_detailed"
    $asticaAPI_prompt_length = '90'; // number of words in GPT response
    
    /*
        '1.0_full' supported options:
            description
            objects
            categories
            moderate
            tags
            brands
            color
            faces
            celebrities
            landmarks
            gpt              (Slow)
            gpt_detailed     (Slower)
            
        '2.0_full' supported options:
            description
            objects
            tags
            describe_all 
            text_read 
            gpt             (Slow)
            gpt_detailed    (Slower)
            
         '2.1_full' supported options:
            Supports all options 
            
    */

    // Define payload array
    $asticaAPI_payload = [
        'tkn' => $asticaAPI_key,
        'modelVersion' => $asticaAPI_modelVersion,
        'input' => $asticaAPI_input,
        'visionParams' => $asticaAPI_visionParams,
        'gpt_prompt' => $asticaAPI_gpt_prompt,
        'prompt_length' => $asticaAPI_prompt_length
    ];
    
    // Call API function and store result
    $result = asticaAPI($asticaAPI_endpoint, $asticaAPI_payload, $asticaAPI_timeout);

    
    //Caption and Describe
    if(isset($result['caption_GPTS']) &&  $result['caption_GPTS'] != '') {
        echo '<hr><b>GPT Caption:</b> '.$result['caption_GPTS'];
    }
    if(isset($result['caption']) &&  $result['caption']['text'] != '') {
        echo '<hr><b>Caption:</b> '.$result['caption']['text'];
    }    
    if(isset($result['caption_list'])) { //v2.0_full only
        echo '<hr><b>Additional Captions:</b> '.count($result['caption_list']);
        foreach($result['caption_list'] as $caption) {
            echo '<li>';
            print_r($caption);
            echo '</li>';
        }
    }
    if(isset($result['caption_tags'])) {
    echo '<hr><b>Caption Tags Found:</b> '.count($result['caption_tags']);
        foreach($result['caption_tags'] as $caption_tags) {
            echo '<li>';
            print_r($caption_tags);
            echo '</li>';
        }
    }
    
    //Object Recognition Output
    if(isset($result['objects'])) {
        echo '<hr><b>Objects Found:</b> '.count($result['objects']);
        foreach($result['objects'] as $object) {
            echo '<li>';
            print_r($object);
            echo '</li>';
        }
    }
    
    //Face Detetion Output
    if(isset($result['faces'])) {
    echo '<hr><b>Faces Found:</b> '.count($result['faces']);
        foreach($result['faces'] as $face) {
            echo '<li>';
            print_r($face);
            echo '</li>';
        }
    }
    
    // Brand Detection Output
    if(isset($result['brand'])) {
    echo '<hr><b>Brands Found:</b> '.count($result['brands']);
        foreach($result['brand'] as $brand) {
            echo '<li>';
            print_r($brand);
            echo '</li>>';
        }
    }
    
    // Generated Tags
    if(isset($result['tags'])) {
    echo '<hr><b>Tags Found:</b> '.count($result['tags']);
        foreach($result['faces'] as $tags) {
            echo '<li>';
            print_r($tags);
            echo '</li>';
        }
    }
    echo '<br><br><hr>API Usage: '.$result['astica']['api_qty'].' transactions';
   
    // Raw Output
    echo '<pre>'; print_r($result); echo '</pre>';
    
    // Define API function
    function asticaAPI($endpoint, $payload, $timeout = 15) {
        $ch = curl_init();
        $payload = json_encode($payload);
        // Set cURL options
        curl_setopt_array($ch, [
            CURLOPT_URL => $endpoint,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $payload,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_SSL_VERIFYPEER => 0,
            CURLOPT_CONNECTTIMEOUT => $timeout,
            CURLOPT_TIMEOUT => $timeout,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json; charset=utf-8',
                'Content-Length: ' . strlen($payload),
                'Accept: application/json'
            ]
        ]);
        $response = curl_exec($ch);
        if (curl_errno($ch)) {
            return curl_error($ch);
        }
        curl_close($ch);        
        $result = json_decode($response, true);
        if(!isset($result['status'])) {
            $result = json_decode(json_decode($response), true);            
        }
        return $result;
    }
?>
Node Computer Vision Code Example
Using Computer Vision with Node JS
Object Detection and Facial Recognition using Node

You can implement computer vision capabilities using Node by using node-fetch.

const axios = require('axios'); //npm install axios
const fs = require('fs'); // Only needed for Input Method 2


//Input Method 1: https URL of a jpg/png image (faster)
var astica_input = 'https://astica.ai/example/asticaVision_sample.jpg';

/*
    //Input Method 2: base64 encoded string of a local image (slower)  
    var path_to_local_file = 'image.jpg';
    var image_data = fs.readFileSync(path_to_local_file);
    var image_extension = path_to_local_file.split('.').pop();
    //For now, let's make sure to prepend appropriately with: "data:image/extension_here;base64" 
    var astica_input = `data:image/${image_extension};base64,${image_data.toString('base64')}`;
*/


const requestData = {
  tkn: 'API KEY HERE',  // visit https://astica.ai
  modelVersion: '2.1_full', // 1.0_full, 2.0_full, or 2.1_full
  input: astica_input,
  visionParams: 'gpt, describe, describe_all, tags, faces', // comma separated, defaults to all
  gpt_prompt: '', // only used if visionParams includes "gpt" or "gpt_detailed"
  prompt_length: 95 // number of words in GPT response
};


axios({
    method: 'post',
    url: 'https://vision.astica.ai/describe',
    data: requestData,
    headers: {
        'Content-Type': 'application/json',
    },
}).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.log(error);
});
Vision AI Code Sample
Computer Vision with jQuery
Describe Images, and Detect Objects using jQuery

You can implement computer vision capabilities by using a simple jQuery AJAX request

Object Detection with jQuery

This is a simple demonstration that can be copy and pasted into the developer tool console of any web browser, after jQuery has been loaded by the page. This is useful for quickly reviewing the output of asticaVision API or other forms of troubleshooting.

var requestData = {
    tkn: 'REPLACE',
    modelVersion: '2.1_full',
    input: "https://www.astica.org/inputs/analyze_3.jpg",
    visionParams: "describe,tags"
};
$.ajax({
    url: "https://vision.astica.ai/describe",
    type: "POST",
    data: JSON.stringify(requestData),
	contentType : "application/json", 
	dataType : "json",
    success: async function (data) {
        console.log(data);
    },
    error: function (xhr, data, status) {
       console.log(data);
       console.log(status);
       console.log(xhr); //statusText
    }
});

You can also use a fetch request without jquery using vanilla javascript:

var requestData = {
    tkn: 'REPLACE',
    modelVersion: '2.1_full',
    input: "https://www.astica.org/inputs/analyze_3.jpg",
    visionParams: "describe,tags"
};
fetch('https://vision.astica.ai/describe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData),
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
Computer Vision with Javascript SDK
Detect Faces and Objects with Javascript
Using the Javascript SDK

Using the javascript SDK it is possible to use computer vision with just one line of code.

//object detection
asticaVision('URL or Base64', 'objects')
//face detection
asticaVision('URL or Base64', 'faces')

Analyze an Image with Computer Vision

You can copy and paste the complete and working sample code found below to perform a computer vision test. Be sure to update the code with your API key generated from your dashboard.

<script src="https://astica.ai/sdk-javascript/astica.api.js"></script>
function asticaVision_example(image_url) {
    asticaVision(
        '1.0_full', //modelVersion: 1.0_full, 2.0_full
        image_url, //Input Image (https URL or Base64)
        'describe,moderate,objects,faces', //or 'all'
        your_astica_CallBack, //Your Custom Callback function
    );           
} 
function your_astica_CallBack(data) {
    if(typeof data.error != 'undefined') { alert(data.error); }         
    console.log(data); //view all data
    
    /* View Individual Data */
    console.log(data.caption); //Image Caption
    console.log(data.caption_list); //Additional Captions (v2.0 only)
    console.log(data.caption_tags); //Caption Tags
    console.log(data.caption_GPTS); //GPT-S Description
    console.log(data.tags); //Image Tags
    console.log(data.categories); //Image Categories
    console.log(data.moderate); //Adult / Sensitive Content
    console.log(data.objects); //Objects Found in Image
    console.log(data.faces); //Faces Found in Image
    console.log(data.brands); //Brands Found in Image
}
setTimeout(function() { 
    asticaAPI_start('API KEY HERE'); //only needs to be called once.   
    asticaVision_example('https://www.astica.org/inputs/analyze_3.jpg'); 
}, 1000);

asticaVision Javascript API ‐ Function

Simple: Output is passed to astica_defaultCB() function

asticaVision(imageUrl, 'objects')

Advanced Usage:

asticaVision(modelVersion, imageUrl, options, callback)

Function Parameters
  • modelVersion: (string) Required.
    The version of the Astica computer vision model to use for the analysis. Current valid values are "1.0_full" and "2.0_full".
  • imageUrl: (string) Required.
    The https URL of the image to be analyzed. You may also base a Base64 encoded string.
  • options: (string) Required.
    Comma separated string of all computer vision parameters to detect. See list
  • callback: (function) Required.
    A callback function that will be called when the analysis is complete. The function should take a single argument, which will be an object containing the analysis results. Optional.

Step #1:
Include the Javascript Library:

Start by including the Astica API library with the following script tag.

This should be added before the closing </head> tag of your website.

<script src="https://astica.ai/sdk-javascript/astica.api.js"></script>

Step #2:
Authenticate with the astica Javascript API:

Next, start the API by calling asticaAPI_start('API KEY HERE');
You only need to call this function once. Make sure to add a valid API key generated from your dashboard.

asticaAPI_start('API KEY HERE');
  • You only need to call this function once.
  • You can generate API keys from the astica dashboard.

  • Step #3:
    Describe and Analyze Images with Javascript

    You are now ready to use asticaVision javascript API to integrate computer vision into your application. To perform a simple test, you can analyze an image using the following code.

    asticaVision('https://www.astica.org/inputs/analyze_3.jpg');

    Note: In this simple example, we do not specify a callback function and so the astica_defaultCB(data) will be used. By default this will emit the output to the console. You can overwrite this function, or read further along to setup your own custom callback.

    Step #4:
    Computer Vision Parameters

    asticaVision can provide a complete dataset for any image with a single API call. This is not economical at large scale because each parameter counts as a transaction. To minimize usage cost of the asticaVision image ai, you should specify only the parameters that you require.

    Notice If no parameters have been specifed, then asticaVision will default to all
    Jump down to Voice List

    Specify parameters using a comma separated string:

    asticaVision('https://www.astica.org/inputs/analyze_3.jpg', 'objects, faces');

    Note: In this simple example, we do not specify a callback function and so the astica_defaultCB(data) will be used. By default this will emit the output to the console. You can overwrite this function, or read further along to setup your own custom callback.


    Optional
    asticaVision ‐ Custom Callback

    asticaVision allows you to specify different model versions, custom callback, and parameters to detect with computer vision. Specifying a custom callback will allow you to catch the javascript variable containing the results.

    asticaVision(
       '2.0_full', //modelVersion: 1.0_full, 2.0_full
        image_url, //Input Image (https URL or Base64)
        'Description,Moderate,Objects,Faces', //or 'all'
        your_astica_CallBack, //Your Custom Callback function
    );
    function your_astica_CallBack(data) {     
        if(typeof data.error != 'undefined') { alert(data.error); return; }      
        console.log(data);
    }

    astica ai Discover More AI

    Experiment with different kinds of artificial intelligence. See, hear, and speak with astica.

    Return to Dashboard
    You can return to this page at any time.
    Success Just Now
    Copied to clipboard
    Success Just Now
    Submission has been received.
    Success Just Now
    Account preferences have been updated.