NAV
cURL PHP Python

Introduction

Vance AI provides a suite of simple and flexible API endpoints to allow you to integrate our AI image processing features into your app or workflow.

Authentication

The Vance AI API requires authentication via an API token generated within your Vance AI account. You can find the API token in the tab of API & Document on "My Account" page.

All of the methods in the Vance AI API require authentication using an api_token.

In this document we use 1234567890abcdefg as the api_token.

Upload image

Request body

curl -X POST "https://api-service.vanceai.com/web_api/v1/upload" \
     -F "api_token=1234567890abcdefg" \
     -F "file=@/Users/vanceai/Downloads/cat.jpg; filename=cat.jpg" \

<?php
  require 'vendor/autoload.php'; 
  use GuzzleHttp\Client; 

  $http_client = new \GuzzleHttp\Client();

  $res = $http_client->post("https://api-service.vanceai.com/web_api/v1/upload", [
    'multipart' => [
      [
          'name' => 'api_token',
          'contents' => '1234567890abcdefg',
      ],
      [
          'name' => 'file',
          'contents' => fopen('/Users/vanceai/Downloads/cat.jpg', 'r'),
      ]
    ]
  ]);

  echo $res->getBody()->getContents();
?>

# Requires "requests" to be installed (see python-requests.org)
import requests
response = requests.post(
    'https://api-service.vanceai.com/web_api/v1/upload',
    files={'file': open('/Users/vanceai/Downloads/cat.jpg', 'rb')},
    data={'api_token': '1234567890abcdefg'},
)
r = response.json()
if r['code'] == 200:
    print('uid:', r['data']['uid'])

Response Success Example:

{
    "code": 200,
    "cscode": 200,
    "data": {
        "uid": "3f8484a52c47b9cc0c34067b5bdf08d3",
        "name": "'cat.png'",
        "thumbnail": "",
        "w": 1200,
        "h": 1199,
        "filesize": 3618416
    },
    "ip": "54.103.172.45"
}

POST https://api-service.vanceai.com/web_api/v1/upload

To do any actions, you should upload the image first. Let's assume we have an image named cat.jpg and the full path is /Users/vanceai/Downloads/cat.jpg. The dimension of this image is 1200x1200px and the file size is 156KB.

Demo image

cat.jpg

So now, let's upload this image by calling upload endpoint.

Uploading will take some times, that depends on the size of your image and your internet speed.

After uploading, you will get the response content with an uid, which will be used in the transform to process your image.

Supported formats

Currently, the supported file formats are JPG and PNG.

Upload limits

The file size can not be larger than 10MB and the max resolution is 34 Megapixels (short for MP).

For example, if the dimension of your image is 7680x4320, then the resolution is 33 MP (33,177,600 pixels), which is less than 34 MP.

If your image exceeds the limits, you will get an error response, then you should resize or compress your image and try to call the upload again.

Parameters

Field Type Description
api_token string Your API token
file file Image file object
job string Optional for AI features. Example: 'ai' for AI features and 'compress' for Compressor.

Process image

Request body

curl -X POST "https://api-service.vanceai.com/web_api/v1/transform" \
     -d 'api_token=1234567890abcdefg' \
     -d 'uid=eb54870e6a45835c540537f79bc7ce5a' \
     -d 'webhook=https://your-domain/path/to/webhook' \
     -d 'jconfig={
            "job": "enlarge",
            "config": {
              "module": "enlarge",
              "module_params": {
                "model_name": "EnlargeStable",
                "suppress_noise": 26,
                "remove_blur": 26,
                "scale": "2x"
              },
              "out_params": {}
            }
          }'

<?php
  $http_client = new \GuzzleHttp\Client([
    'base_uri' => 'https://api-service.vanceai.com',
    'verify'  => false,
  ]);

  $json_string = file_get_contents("/Users/vanceai/Downloads/enlarge.json");
  $json_string = trim($json_string,chr(239).chr(187).chr(191));

  $response = $http_client->request('POST','/web_api/v1/transform', [
      'form_params' => [
          'api_token' =>  '1234567890abcdefg',
          'uid' => 'b0c5b210dd1a698d0554bca3d1bdd7b4',
          'jconfig' => $json_string,
          'webhook' => 'https://your-domain/path/to/webhook',
      ]
  ]);

  echo $response->getBody()->getContents();
?>

import requests
import json

json_path = "/Users/vanceai/Downloads/enlarge.json"
jparam={}
with open(json_path, 'rb') as f:
    jparam = json.load(f)

data={
    'api_token': '1234567890abcdefg',
    'uid': 'b0c5b210dd1a698d0554bca3d1bdd7b4',
    'jconfig': json.dumps(jparam),
    'webhook': 'https://your-domain/path/to/webhook'
    }
response = requests.post(
    'https://api-service.vanceai.com/web_api/v1/transform',
     data)
r = response.json()
if r['code'] == 200:
    print('trans_id:', r['data']['trans_id'])

Response Success Example:

{
    "code": 200,
    "cscode": 200,
    "data": { 
        "trans_id": "6de4b562d1a01c3d2520608eae929646", //Transform Job ID
        "status": "webhook", // waiting, finish, fatal, process, webhook
    },
    "ip":"54.103.172.45"
}

POST https://api-service.vanceai.com/web_api/v1/transform

When we get the uid in the first upload step, we can use it to call the transform endpoint.

The transform needs 3 parameters at least. Besides api_token and uid, we also need an AI configuration in json format as the value of jconfig.

Assume we have an AI enlarger config file stored in Downloads folder, so the full path is /Users/vanceai/Downloads/enlarge.json.

Parameters

Field Type Description
api_token string Your API token
uid string ID of uploaded file
jconfig string Transform parameter in json format
webhook string [Optional]The callback url to receive the transfrom result notification.

Status of job processing

You may get different job status from the transform response. These statuses indicate different processing results of your job.

Status Description
finish The job has finished, now you can download the result with the trans_id
waiting Your job is waiting to be assigned in the queue, all servers are busy, you may need to wait for a while.
fatal Your job is failed, you can try again or contact us.
process Your job is still being processed, please wait a secend.
webhook You see this status, because you provided the webhook url, so it means the processing result will be sent via webhook.
busy It means your job is in the queue, you may need to call "progress" to query the status in a fixed frequency, such as to query the status ever 2 seconds.

Webhook

The webhook is an optional parameter, which is used to receive message of job processing result. To use webhook, you should set the webhook field to point to your webserver in our transform request body. This url can be http or https.

If you provide the callback url, then the transform will response immediately after calling instead of waiting for the process result.

You will get a trans_id from the transform response body. Once the job finished, we will send a POST request to the endpoint you specified with webhook. You can also query the progress with the trans_id by calling the progress endpoint.

Example: https://your.domain/path/to/webhook

Note: the protocol must be https.

Check the progress

Request body

curl -X POST "https://api-service.vanceai.com/web_api/v1/progress" \
       -d 'api_token=1234567890abcdefg' \
       -d 'trans_id=6de4b562d1a01c3d2520608eae929646' \

<?php
  $remoteFileUrl = 'https://api-service.vanceai.com/web_api/v1/progress?trans_id=fe854a3b20237f70d1efb757b6aa0cc4&api_token=1234567890abcdefg';

  $ch = curl_init();
  $timeout = 60;
  curl_setopt($ch, CURLOPT_URL, $remoteFileUrl);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
  $img = curl_exec($ch);
  curl_close($ch);
?>

remoteFileUrl = 'https://api-service.vanceai.com/web_api/v1/progress?trans_id=fe854a3b20237f70d1efb757b6aa0cc4&api_token=1234567890abcdefg''
response = requests.get(remoteFileUrl)
r = response.json()
if r['code'] == 200:
    print('status:', r['data']['status'])

Response Success Example:

{
    "code": 200,
    "cscode": 200,
    "data": {
        "status": "finish", // waiting, finish, fatal, process
        "filesize": "16794935"
    },
    "ip": "54.103.172.45"
}

GET|POST https://api-service.vanceai.com/web_api/v1/progress

We recommend you to use this endpoint in two situations:

Parameters

Field Type Description
api_token string Your API token
trans_id string ID in transform response

Download result

Request body

curl -X POST "https://api-service.vanceai.com/web_api/v1/download" \
     -o /Users/vanceai/Downloads/enlarged-cat.jpg \
     -d 'api_token=1234567890abcdefg' \
     -d 'trans_id=6de4b562d1a01c3d2520608eae929646' \

<?php
  $remoteFileUrl = 'https://api-service.vanceai.com/web_api/v1/download?trans_id=fe854a3b20237f70d1efb757b6aa0cc4&api_token=1234567890abcdefg';

  dst_path = '/path/to/save/demo.jpg';

  $ch = curl_init();
  $timeout = 60;
  curl_setopt($ch, CURLOPT_URL, $remoteFileUrl);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
  $img = curl_exec($ch);
  curl_close($ch);

  $fp2 = @fopen(dst_path, 'a');
  fwrite($fp2, $img);
  fclose($fp2);
?>

remoteFileUrl = 'https://api-service.vanceai.com/web_api/v1/download?trans_id=fe854a3b20237f70d1efb757b6aa0cc4&api_token=1234567890abcdefg'
dst_path = '/path/to/save/demo.jpg'

response = requests.get(remoteFileUrl, stream=True)

f = open(dst_path, "wb")
for chunk in response.iter_content(chunk_size=512):
    if chunk:
        f.write(chunk)
f.close()

GET|POST https://api-service.vanceai.com/web_api/v1/download

Once the status of the job is finish, we should use download endpoint to save the result.

Let download the result to the path of '/Users/vanceai/Downloads/' and named it as 'enlarged-cat.jpg'.

Parameters

Field Type Description
api_token string Your API token
trans_id string ID in transform response

Comparison of before and after

AI enlarger Before and After comparision

As you can see, the cat.jpg has been enlarged by 200%, the output dimension is 2400x2400px, but the quality is not lost, even better than before.

Errors

Response Error Example

{
    "code": 10001, 
    "msg": "Illegal Parameter"
}

OR

{
    "code": 30001, 
    "msg": {    
           "api_token": [
                 "The api token field is required."
            ]
     }
}

The VanceAI API uses the following error codes:

Error Code Meaning
10001 Illegal parameter
10010 Internal error
10011 File doesn't exist OR Invalid download link
10012 Resolution or file size exceeds the limits.
10013 jparam parse error
10014 Job failed and exited for unexpected reason
30001 Invalid API token
30004 Insufficient credits

API Management

API Usage

Check credit balance

Request body

curl -X GET "https://api-service.vanceai.com/web_api/v1/point?api_token=1234567890abcdefg"

Response Success Example

{
    "code": 200,
    "cscode": 200,
    "data": {
        "max_num": "500.000", // Total Credits
        "used_num": "107.800" // Used Credits
    },
    "ip": "54.103.172.45"
}

GET https://api-service.vanceai.com/web_api/v1/point

You can use this endpoint to query your credit balance.

Parameters

Field Type Description
api_token string Your API token

Credit usage history

Request body

curl -X POST "https://api-service.vanceai.com/web_api/v1/points/record" \
     -d 'api_token=1234567890abcdefg' \
     -d 'page=1' \
     -d 'limit=20' \

Response Success Example

{
    "code": 200,
    "cscode": 200,
    "data": {
        "datas": [
            {
                "point_type": "download", // job or download
                "job": "denoise",         //job type
                "info": "denoise_SwJes_0.jpg.jpg", // Image name
                "point": "1.000",         // Credits cost for this job or download
                "balance": "392.200",     // Credit balance
                "created_at": "2021-12-14 04:36:18"
            }
        ],
        "current_page": 1,
        "last_page": 5, 
        "per_page": 20,
        "total": 100
    }
    "ip": "54.103.172.45"
}

GET|POST https://api-service.vanceai.com/web_api/v1/points/record

You can use this endpoint to query your credit usage history.

Parameters

Field Type Description
api_token string Your API token
page numeric [Optional] The xth page of pagination. Default: 1
limit numeric [Optional] The number of items to display per page. Default: 20

Credit Costs

Each AI feature has its own value. Currently all of the features will cost 0.2 credits when the transform status is finish.

Workflow will cost 0.2 x [steps] credits. If you have a 3-step workflow, then process one image will cost 0.6 credits.

Upload, processing failed or check progress don't charge credits.

Download the result will cost 1 credit, duplicate downloads won't charge credits.

Config Files

VanceAI currently has 12 AI features for image enhancement, each one has one config file at least. And we are continue to add more AI features which will cover the fields of image, video and music.

Generally, all the config files have a fixed structure. let's take an example by using AI Enlarger.

Structure of config file

Configuration is required when calling transform endpoint. VanceAI supports single feature mode and workflow (combination of multiple steps) mode.

Single Feature

Single Feature Configuration

{
    "job": "enlarge",
    "config": {
        "module": "enlarge",
        "module_params": {
            "model_name": "EnlargeStable",
            "suppress_noise": 26,
            "remove_blur": 26,
            "scale": "2x"
        },
        "out_params": {
          "compress": {
            "quality": 95
          },
          "dpi": 300,
          "format": "png",
          "bg_composed": {
            "bg_color": {
              "r": 0,
              "g": 255,
              "b": 255
            }
          }
        }
    }
}

Single feature means to process image with only one feature, like enlarge, denoise or colorise.

To process an image, you will need to send a job to the cloud server. We use job to tell the server what kind of job is it. In this case, the job is enlarge.

In the config, we config which module to use and the related module_params. And in the out_params, it defines some parameters of the output file, such as the format, quality and dpi.

Workflow

Workflow Configuration

{
    "job": "workflow",
    "config": [
        {
            "name": "enlarge",
            "config": {
                "module": "enlarge",
                "module_params": {
                    "model_name": "EnlargeStable",
                    "autoparams": false,
                    "suppress_noise": 65,
                    "remove_blur": 65,
                    "scale": "1x"
                }
            }
        },
        {
            "name": "matting",
            "config": {
                "module": "matting",
                "module_params": {
                    "model_name": "MattingStable",
                    "rescale": 532
                },
                "out_params": {
                    "compress": {
                        "quality": 100
                    },
                    "bg_composed": {
                        "bg_color": {
                            "r": 132,
                            "g": 142,
                            "b": 109
                        }
                    },
                    "dpi": 72,
                    "format": "jpg"
                }
            }
        }
    ]
}

You can also add multiple features in the configuration, the server will process your image in the order of the added features.

There are some differences between the structure of the Workflow configuration file and the single feature. For details, you can check the demo code.

The demo code provides a two-step workflow, the first step is enlarge, the second step is background remove.

You can use our workflow configuration generator to build your json file.

Supported output parameters

Settings Type Example Note
Quality int {"compress": {"quality": 95}} The range is 0-100, the higher the number, the compress the less.
DPI int {"dpi": 300} The range is 0-2000 (suggested). Generally, 300 or 350 is suitable for print.
Format string {"format": "png"} Now we only accept jpg and png.
Background Color int {"bg_composed": {"bg_color": {"r": 0, "g": 255, "b": 255}}} This can be used to set a solid background color to the background removed photo.

Description of config file

AI Image Enlarger

AI Image Enlarger

{
    "job": "enlarge",
    "config": {
        "module": "enlarge",
        "module_params": {
            "model_name": "EnlargeStable",
            "auto_params": true,
            "suppress_noise": 26,
            "remove_blur": 26,
            "scale": "2x"
        }
    }
}

Enlarge image up to 800% while keeping high quality.

Key Value Description
job enlarge
module enlarge
model_name EnlargeStable
auto_params true or false If true, then suppress_noise and remove_blur will be ignored. AI will select property values automatically according to the training.
suppress_noise 0 - 100
remove_blur 0 - 100
scale 2x, 4x, 6x, 8x

AI Image Denoiser

AI Image Denoiser

{
    "job": "denoise",
    "config": {
        "module": "denoise",
        "module_params": {
            "model_name": "DenoiseStable",
            "auto_params": true,
            "remove_noise": 75,
            "sharpen" : 75
        }
    }
}

It removes grain and noise from photo effortlessly through AI-powered denoise algorithms.

Key Value Description
job denoise
module denoise
model_name DenoiseStable
auto_params true or false If true, then remove_noise and sharpen will be ignored. AI will select property values automatically according to the training.
remove_noise 0 - 100
sharpen 0 - 100

AI Image Sharpener

AI Image Sharpener

{
    "job": "sharpen",
    "config": {
        "module": "sharpen",
        "module_params": {
            "model_name": "SharpenStable",
            "auto_params": true,
            "sharpness": 75,
            "suppress_noise": 75
        }
    }
}
Key Value Description
job sharpen
module sharpen, debouncing Two modules available, sharpen for softness images and debouncing for motion blur images.
model_name SharpenStable, DebouncingStable
auto_params true or false If true, then sharpeness and suppress_noise will be ignored. AI will select property values automatically according to the training.
sharpeness 0 - 100
suppress_noise 0 - 100

AI Background Remover

AI Background Remover

This config is mainly for object coutout.

{
    "job": "matting",
    "config": {
        "module": "matting",
        "module_params": {
            "model_name": "MattingStable",
            "rescale": 532
        }
    }
}
Key Value Description
job matting
module matting
model_name MattingStable
rescale 532 The internal code of the recognition accuracy.

AI Portrait Background Remover

This config is specified to human portrait cutout.

{
    "job": "matting",
    "config": {
        "module": "portrait_matting",
        "module_params": {
            "model_name": "PortraitMattingStable",
            "no_face_blur": false
        }
    }
}
Key Value Description
job matting
module portrait_matting
model_name PortraitMattingStable
no_face_blur false

AI Anime Upscaler

AI Anime Upscaler - waifu

{
  "job": "waifu",
  "config": {
    "module": "waifu",
    "module_params": {
      "model_name": "models-cunet",
      "noise_level": 2,
      "scale": "2x"
    }
  }
}

Model of waifu

Key Value Description
job waifu
module waifu
model_name models-cunet, models-upconv_7_anime_style_art_rgb 2 models for waifu
noise_level 0, 1, 2, 3 The level of reduce noise. 0: No, 1: Little, 2: Medium, 3: Much
scale 2x, 4x, 8x, 16x

AI Anime Upscaler - real_esrgan

{
    "job":"real_esrgan",
    "config": {
        "module":"real_esrgan",
        "module_params": {
            "model_name": "RealEsrganStable",
            "scale": "2x"
        }
    }
}

Model of RealEsrgan

Key Value Description
job real_esrgan
module real_esrgan
model_name RealEsrganStable
scale 1x, 2x, 4x, 6x, 8x If selected 1x, it will only enhance the quality without enlargement.

AI JPEG Artifacts Remover

AI JPEG Artifacts Remover

{
    "job":"jpeg_artifact",
    "config": {
        "module": "hinet_jpeg",
        "module_params": {
            "model_name": "HinetStable",
            "deblur": true
        }
    }
}
Key Value Description
job jpeg_artifact
module hinet_jpeg
model_name HinetStable
deblur true or false An option for if you want to deblur the image.

AI Photo Dehaze

AI Photo Dehaze

{
    "job":"se-dehazing",
    "config":[
        {
            "name":"dehazing",
            "config":{
                "module":"dehazing",
                "module_params":{
                    "model_name":"DehazingStable",
                    "contrast":1,
                    "brightness":20
                }
            }
        },
        {
            "name":"jpeg_artifact",
            "config":{ 
                "module":"hinet_jpeg",
                "module_params":{
                    "model_name":"HinetStable",
                    "deblur":true
                }
            }
        }
    ]
}

For a better result, this feature is a 2-step workflow by default. The table below only lists the parameters in dehazing.

Key Value Description
job se-dehazing
module dehazing
model_name DehazingStable
contrast 0.0 - 2.0 Set the contrast of output image. Default: 1
brightness 0 - 100 Set the brightness of output image. Default: 20

AI Photo Restorer

AI Photo Restorer

{
    "job": "repair",
    "config": {
        "module": "repair",
        "module_params": {
            "model_name": "RepairStable",
            "with_scratch": true,
            "inpainting": true
        }
    }
}
Key Value Description
job repair
module repair
model_name RepairStable
with_scratch true or false Set to true to remove scratches.
inpainting true or false Set to true to inpaint damaged area.

Toongineer Cartoonizer

Toongineer Cartoonizer

{
    "job": "cartoonize",
    "config": {
        "module": "cartoonize",
        "module_params": {
            "model_name": "CartoonizeStable"
        }
    }
}
Key Value Description
job cartoonize
module cartoonize
model_name CartoonizeStable

VancePortrait

VancePortrait - AnimeGANv2

{
    "job": "animegan",
    "config": {
        "module": "animegan2",
        "module_params": {
            "model_name": "Animegan2Stable",
            "single_face": true
        }
    }
}

Model of AnimeGANv2

This model will convert portrait to anime style.

Anime Style

Key Value Description
job animegan
module animegan2
model_name Animegan2Stable
single_face true or false Set to true to only convert human face. Default: true

VancePortrait - Sketch

{
    "job": "sketch",
    "config": {
        "module": "sketch",
        "module_params": {
            "model_name": "SketchStable",
            "single_face": true,
            "composite": true,
            "sigma": 0,
            "alpha": 0
        }
    }
}

Model of AnimeGANv2

This model will convert image to sketch style.

Sketch Style

Key Value Description
job sketch
module sketch
model_name SketchStable
single_face true or false Set to true to only convert human face. Default: true
composite true or false Set to true to enable sigma and alpha.
sigma 0 - 100 Set the softness of the result.
alpha 0 - 100 Set the saturation of the result.

You can use the preset value below:

Sketch Preset Value

0 1 2 3
1 Sigma: 0, Alpha: 0 Sigma: 2, Alpha: 0.35 Sigma: 20, Alpha: 0.35
2 Sigma: 2, Alpha: 0.5 Sigma: 10, Alpha: 0.5 Sigma: 20, Alpha: 0.5
3 Sigma: 2, Alpha: 0.75 Sigma: 10, Alpha: 0.75 Sigma: 20, Alpha: 0.75

AI Photo Colorizer

AI Photo Colorizer

{
    "job": "colorize",
    "config": {
        "module": "deoldify",
        "module_params": {
            "model_name": "ColorizeStable_pth",
            "render_factor": 30
        }
    }
}
Key Value Description
job colorize
module colorize or deoldify colorize is fast but deoldify has a better output.
model_name ColorizeStable_pth or ColorizeStable deoldify -> ColorizeStable_pth, colorize -> ColorizeStable
render_factor 0 - 40 Default: 30 for deoldify and 10 for colorize

AI Photo Retoucher

AI Photo Retoucher

{
    "job": "perfect",
    "config": {
        "module": "perfect",
        "module_params": {
            "model_name": "perfect_2k"
        }
    }
}
Key Value Description
job perfect
module perfect
model_name perfect_2k

Download Config Files

Download the Config Files here.

cURL PHP Python