BEIA Image Processing API

Official API documentation for image processing on the BEIA server.

1. General Description

The API allows you to send an image together with access credentials (licenseId and apiKey) for processing. As a result, the service can return a single processed image in PNG format or, depending on the input parameters, a set of images in a multipart/mixed response.

For security reasons, all requests must originate from a previously authorized static IP address. Requests made from unregistered IP addresses will be rejected.

2. Endpoint

POST https://aws.beiatechnology.com/beia-api/v1/image

3. Network Requirements

All requests must be made from a previously authorized static IP address. Requests from other IPs will be rejected.

4. Request Parameters (multipart/form-data)

NameTypeLocationDescriptionDefault Value
licenseIdstringHeader / FormClient license ID.Required
apiKeystringFormAuthentication key.Required
imagefileFormImage to be processed.Required
includeCroppedImageboolFormIndicates whether the cropped image should be included in the response. This parameter modifies the response format returned by the API.false

Required Headers

HeaderDescriptionRequired
License-IdMust match the submitted licenseId.Yes
Content-Typemultipart/form-dataYes

5. Response

The API can return two different response formats depending on the parameters sent in the request.

Single image response:

When no additional images are requested, the response consists of a single processed image in PNG format, with MIME type image/png.

Multipart/mixed response:

When additional results are requested (for example, the cropped image), the API returns a multipart/mixed response, which may contain the following elements:

  • result: main processed image.
  • cropped: cropped image (if requested).
  • credits: remaining credits.

Additionally, all responses include the HTTP header Credits-Remaining, which indicates the number of credits available after processing the request.

Status Codes

CodeDescription
200 OKRequest processed successfully.
400 Bad RequestMissing or invalid parameters.
401 UnauthorizedInvalid license.
402 Payment RequiredNo credits remaining.
403 ForbiddenUnauthorized IP.
415 Unsupported Media TypeInvalid file.
429 Too Many RequestsToo many images being processed, please try again later.
500 Internal Server ErrorInternal server error.

6. Examples

cURL Request

curl -X POST "https://aws.beiatechnology.com/beia-api/v1/image" \
	-H "License-Id: 1234" \
	-F "image=@d:\eco\001.jpg;filename=001.jpg" \
	-F "apiKey=5678" \
	-F "licenseId=1234" \
	-o result.png

Python

Download API connection example

View code
"""
Beia API Sample - Python Version
Minimal error checking for clarity.
"""

import os
import requests

# Configuration
IMAGE_PATH = "./001.jpg"
LICENSE_ID = ""
API_KEY = ""
ENDPOINT_URL = "https://aws.beiatechnology.com/beia-api/v1/image"


def validate_inputs():
    """Validates that all required inputs are present."""
    if not os.path.exists(IMAGE_PATH):
        print(f"Image file '{IMAGE_PATH}' not found")
        return False
    
    if not LICENSE_ID or not LICENSE_ID.strip():
        print("License ID is not set")
        return False
    
    if not API_KEY or not API_KEY.strip():
        print("API key is not set")
        return False
    
    return True

def main():
    """Main function - sends image to Beia API and processes response."""
    
    if not validate_inputs():
        return
    
    # Read image file
    with open(IMAGE_PATH, 'rb') as f:
        image_bytes = f.read()
    
    # Prepare headers
    # License ID header is recommended for load balancing purposes
    headers = {
        'License-Id': LICENSE_ID
    }
    
    # Build the multipart/form-data request body
    files = {
        'apiKey': (None, API_KEY),
        'licenseId': (None, LICENSE_ID),
        'image': (IMAGE_PATH, image_bytes, 'application/octet-stream')
    }
    
    try:
        print("Sending request to Beia API...")
        response = requests.post(ENDPOINT_URL, headers=headers, files=files)
        
        if not response.ok:
            if response.status_code == 403:
                print("This IP is not authorized to use the API. Please contact Beia support.")
                return
            
            print(f"Response code: {response.status_code}")
            return
        
        result_bytes = response.content
        print(f"Received {len(result_bytes)} bytes")
        
        with open("result.png", "wb") as f:
            f.write(result_bytes)
        print("Result image saved to 'result.png'")
        
    except Exception as ex:
        print(f"Exception: {ex}")


if __name__ == "__main__":
    main()

Node.js

Download API connection example

View code
/**
 * Beia API Sample - Node.js Version
 * Minimal error checking for clarity.
 * 
 * Requirements: npm install axios form-data
 */

const fs = require('fs').promises;
const fsSync = require('fs');
const path = require('path');
const axios = require('axios');
const FormData = require('form-data');

// Configuration
const IMAGE_PATH = './001.jpg';
const LICENSE_ID = '';
const API_KEY = '';
const ENDPOINT_URL = 'https://aws.beiatechnology.com/beia-api/v1/image';

function validateInputs()
{
    if (!fsSync.existsSync(IMAGE_PATH))
    {
        console.log(`Image file '${IMAGE_PATH}' not found`);
        return false;
    }
    
    if (!LICENSE_ID || !LICENSE_ID.trim())
    {
        console.log('License ID is not set');
        return false;
    }
    
    if (!API_KEY || !API_KEY.trim())
    {
        console.log('API key is not set');
        return false;
    }
    
    return true;
}

async function main()
{
    if (!validateInputs())
    {
        return;
    }
    
    try
    {
        const imageBuffer = await fs.readFile(IMAGE_PATH);
        
        const formData = new FormData();
        formData.append('apiKey', API_KEY);
        formData.append('licenseId', LICENSE_ID);
        formData.append('image', imageBuffer,
        {
            filename: path.basename(IMAGE_PATH),
            contentType: 'application/octet-stream'
        });
        
        const headers =
        {
            ...formData.getHeaders(),
            'License-Id': LICENSE_ID
        };
        
        console.log('Sending request to Beia API...');
        const response = await axios.post(ENDPOINT_URL, formData,
        {
            headers: headers,
            responseType: 'arraybuffer'
        });
        
        const resultBytes = Buffer.from(response.data);
        console.log(`Received ${resultBytes.length} bytes`);
        
        await fs.writeFile('result.png', resultBytes);
        console.log("Result image saved to 'result.png'");
        
    }
    catch (error)
    {
        if (error.response)
        {
            if (error.response.status === 403)
            {
                console.log('This IP is not authorized to use the API. Please contact Beia support.');
                return;
            }
            
            console.log(`Response code: ${error.response.status}`);
        }
        else
        {
            console.log(`Exception: ${error.message}`);
        }
    }
}

main();

C#

Download API connection example

View code
using System;
using System.ComponentModel;
using System.Net.Http.Headers;

class Program
{
	const string ImagePath = "./001.jpg";
	const string LicenseId = "";
	const string ApiKey = "";
	const string EndpointUrl = "https://aws.beiatechnology.com/beia-api/v1/image";

	static async Task Main (string[] args)
	{
		if (!ValidateInputs ()) return;

		byte[] imageBytes = File.ReadAllBytes (ImagePath);

		using HttpClient client = new HttpClient ();

		client.DefaultRequestHeaders.Add ("License-Id", LicenseId);

		MultipartFormDataContent formData = new MultipartFormDataContent ();
		formData.Add (new StringContent (ApiKey), "apiKey");
		formData.Add (new StringContent (LicenseId), "licenseId");
		formData.Add (new ByteArrayContent (imageBytes), "image", ImagePath);

		try
		{
			Console.WriteLine ("Sending request to Beia API...");
			HttpResponseMessage response = await client.PostAsync (EndpointUrl, formData);

			if (!response.IsSuccessStatusCode)
			{
				if (response.StatusCode == System.Net.HttpStatusCode.Forbidden)
				{
					Console.WriteLine ("This IP is not authorized to use the API. Please contact Beia support.");
					return;
				}

				Console.WriteLine ($"Response code: {(int)response.StatusCode}");
				return;
			}

			byte []resultBytes = await response.Content.ReadAsByteArrayAsync();
			Console.WriteLine ($"Received {resultBytes.Length} bytes");

			File.WriteAllBytes ("result.png", resultBytes);
			Console.WriteLine ("Result image saved to 'result.png'");
		}
		catch (Exception ex)
		{
			Console.WriteLine ("Exception: " + ex.Message);
		}
	}

	static bool ValidateInputs ()
	{
		if (!File.Exists (ImagePath))
		{
			Console.WriteLine ($"Image file '{ImagePath}' not found");
			return false;
		}

		if (string.IsNullOrWhiteSpace (LicenseId))
		{
			Console.WriteLine ("License ID is not set");
			return false;
		}

		if (string.IsNullOrWhiteSpace (ApiKey))
		{
			Console.WriteLine ("API key is not set");
			return false;
		}

		return true;
	}
}