Developer Documentation

asticaVision - Image AI API

Computer Vision ‐ Public Preview v1.0
asticaVision - Computer Vision API

asticaVision is a state-of-the-art general-purpose computer vision model. With asticaVision, you can easily incorporate computer vision capabilities into your applications using our REST API or JavaScript API.

Designed to recognize a wide range of visual patterns, from simple shapes and colors to complex objects and scenes. The model is trained on a vast dataset of images, using deep learning techniques to identify and classify visual patterns with high accuracy.

Multi-purpose Computer Vision Model

asticaVision can be used for various image ai related tasks with high performance.

  • Describe Images
  • Detect Objects
  • Detect Text (OCR)
  • Detect Age
  • Detection Faces
  • Detection Gender
  • Detect Adult Content
  • Detect Celebrities
  • Detect Location (Landmarks)
  • Detect Species, Make and model (Plant or Animal, Vehicles)
  • Categorize and Tag Images
Visit the Online Demo
Getting Started

asticaVision allows you to analyze an image or video still using computer vision. It can be used to describe images, automatically moderate user uploads, and determine details such as the species of an animal or plant.

Ways to Integrate asticaVision - Image AI API
Javascript Computer Vision API

asticaVision is included within the core astica Javascript API. After including the necessary script, you can begin using asticaVision image AI with one line of javascript.

Designed to be plug and play for automated image captions, categorization and moderation within your application. asticaVision can be used to analyze user submitted images before the image is posted publicly.

Jump down to Javascript Documentation
Rest API Endpoint

You can also access asticaVision using a simple REST API. Use a POST request containing a valid URL to receive the detected objects, image description and parameters that you specify.

Jump down to Rest API Documentation

Integrating the Javascript Computer Vision API

You can copy and paste the working sample code found below. You can also following along for a step by step integration tutorial.

<script src="https://astica.ai/javascript-sdk/2023-07-09/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)
        '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); }         
    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://astica.ai/example/asticaVision_sample.jpg'); 
}, 1000);

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/javascript-sdk/2023-07-09/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://astica.ai/example/asticaVision_sample.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://astica.ai/example/asticaVision_sample.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);
    }

    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. 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.

    Computer Vision ‐ 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.

    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.

    View Example Codes on Github

    Rest API Overview
    • To use Astica API, you need to sign up and obtain an API key from the Astica 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 API currently supports two different models: version 1.0_full and version 2.0_full.
    • 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)
      • visionParams (optional): a comma-separated list of options that determine which metadata is returned. Options include description, objects, categories, moderate, tags, brands, color, faces, celebrities, landmarks, gpt, gpt_detailed, describe_all, text_read
      • input (required): HTTPS URL or Base64 encoded string of the image to be analyzed.
    • The API returns a JSON response that includes the following metadata based on provided visionParams:
      • 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

    Making CURL Requests

    curl --location --request POST 'https://vision.astica.ai/describe' \
    --header 'Content-Type: application/json' \
    --insecure \
    --data '{
      "tkn": "key",
      "modelVersion": "1.0_full",
      "input": "https://astica.ai/example/asticaVision_sample.jpg",
      "visionParams": "describe"
    }'

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


    asticaVision jQuery ‐ API Example

    var requestData = {
               tkn: 'TKN_HERE',
               modelVersion: '1.0_full',
               input: "https://astica.ai/example/asticaVision_sample.jpg",
               "visionParams": "description,tags"
           };
           $.ajax({
               url: "https://vision.astica.ai/describe",
               type: "POST",
               data: requestData,
               dataType : "html",
               success: async function (data) {
                   var data = JSON.parse(data);
                   console.log(data);
               },
               error: function (xhr, data, status) {
                   console.log(data);
                   console.log(status);
                   console.log(xhr); //statusText
               }
           });
    

    asticaVision Python ‐ REST API Example

    import requests
    import json
    
    def asticaAPI(endpoint, payload, timeout):
        response = requests.post(endpoint, data=payload, timeout=timeout, verify=False)
        if response.status_code == 200:
            return response.json()
        else:
            return {'status': 'error', 'error': 'Failed to connect to the API.'}
    
    asticaAPI_key = 'YOUR API KEY' # visit https://astica.org
    asticaAPI_key = '8FFDF928-3CCB-4964-A3FF-130CAD42344D' # visit https://astica.org
    asticaAPI_timeout = 35 # seconds
    
    asticaAPI_endpoint = 'https://vision.astica.ai/describe'
    asticaAPI_modelVersion = '2.1_full' # '1.0_full', '2.0_full', or '2.1_full'
    
    asticaAPI_input = 'https://astica.ai/example/asticaVision_sample.jpg'
    asticaAPI_visionParams = 'gpt,description,objects,faces' # comma separated options; leave blank for all; note "gpt" and "gpt_detailed" are slow.
    '''
        '1.0_full' supported options:
            description
            objects
            categories
            moderate
            tags
            brands
            color
            faces
            celebrities
            landmarks
            gpt new (Slow - be patient)
            gpt_detailed new (Much Slower)
    
        '2.0_full' supported options:
            description
            objects
            tags
            describe_all new
            text_read new
            gpt new (Slow - be patient)
            gpt_detailed new (Much Slower)
            
        '2.1_full' supported options:
            Supports All Options
    '''
    
    # Define payload dictionary
    asticaAPI_payload = {
        'tkn': asticaAPI_key,
        'modelVersion': asticaAPI_modelVersion,
        'visionParams': asticaAPI_visionParams,
        'input': asticaAPI_input,
    }
    
    # Call API function and store result
    asticaAPI_result = asticaAPI(asticaAPI_endpoint, asticaAPI_payload, asticaAPI_timeout)
    
    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')
    

    asticaVision PHP ‐ REST API Example

    <?php    
        $asticaAPI_key = 'YOUR API KEY'; //visit https://astica.ai
        $asticaAPI_timeout = 35; //seconds
    
        $asticaAPI_endpoint = 'https://vision.astica.ai/describe';
        $asticaAPI_modelVersion = '2.1_full';  //1.0_full or 2.0_full  
    
        $asticaAPI_input = 'https://astica.ai/example/asticaVision_sample.jpg';
        $asticaAPI_visionParams = 'gpt, description, objects, faces'; //comma separated options; leave blank for all; note "gpt" and "gpt_detailed" are slow.
        /*
            '1.0_full' supported options:
                description
                objects
                categories
                moderate
                tags
                brands
                color
                faces
                celebrities
                landmarks
                gpt new (Slow - be patient)
                gpt_detailed new (Much Slower)
                
            '2.0_full' supported options:
                description
                objects
                tags
                describe_all new
                text_read new
                gpt new (Slow - be patient)
                gpt_detailed new (Much Slower)
         */
    
        // Define payload array
        $asticaAPI_payload = [
            'tkn' => $asticaAPI_key,
            'modelVersion' => $asticaAPI_modelVersion,
            'visionParams' => $asticaAPI_visionParams,
            'input' => $asticaAPI_input,
        ];
        
        // Call API function and store result
        $result = asticaAPI($asticaAPI_endpoint, $asticaAPI_payload, $asticaAPI_timeout);
    
        
        ///////////////////Caption
        if(isset($result['caption_GPTS']) &&  $result['caption_GPTS'] != '') {
            echo '<hr><b>GPT Caption:</b> '.$result['caption_GPTS'].'<hr>';
        }
        if(isset($result['caption']) &&  $result['caption']['text'] != '') {
            echo '<hr><b>Caption:</b> '.$result['caption']['text'].'<hr>';
        }
    
        //////////Detailed Caption
        if(isset($result['CaptionDetailed']) &&  $result['CaptionDetailed']['text'] != '') {
            echo '<hr><b>CaptionDetailed:</b> '.$result['CaptionDetailed']['text'].'<hr>';
        }
    
    
        ///////////////////Objects
        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>';
            }
        }
    
        /////////////////////Faces
        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>';
            }
        }
    
        ////////////////////Brands
        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>';
            }
        }
        
        //////////////////////Tags
        if(isset($result['tags'])) {
            echo '<hr>Tags: ';
            echo implode(', ', $result['tags']);
        }
        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();
            curl_setopt_array($ch, [
                CURLOPT_URL => $endpoint,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => http_build_query($payload),
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_SSL_VERIFYHOST => 0,
                CURLOPT_SSL_VERIFYPEER => 0,
                CURLOPT_CONNECTTIMEOUT => $timeout,
                CURLOPT_TIMEOUT => $timeout
            ]);
            $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;
        }
    ?>