sf-api

The sf-api service implements the HTTP API for the main functionality of the FindFace Server such as object detection and object recognition.

Note

The mentioned functions themselves are provided by extraction-api.

The sf-api interfaces with the following FindFace Server components:

  • feature vector database powered by Tarantool via the tntapi service

  • extraction-api that provides object detection and object recognition

  • upload that provides a storage for original images and FindFace Server artifacts

To detect an object in an image, you need to send the image as a file or URL in an API request to sf-api. The sf-api will then redirect the request to extraction-api for object detection and recognition.

If there is a configured video object detection module in the system, sf-api also interfaces with the router service (e.g. facerouter). It receives data of detected objects and processing directives from the router service (facerouter) and executes the received directives (for example, saves objects into a specific database gallery).

Tip

You can also directly access extraction-api.

Functionality:

  • HTTP API implementation (object detection and object recognition methods, performed via extraction-api).

  • saving object data to the feature vector database (performed via tntapi),

  • saving original images, object thumbnails and normalized object images to an NginX-powered web server (via upload).

  • provides interaction between all the FindFace Server components.

The sf-api configuration is done through environment variables and command line flags or through the sf-api.yaml configuration file. You can find its default content here.

When configuring sf-api, refer to the following parameters:

Command line flags

Type

Description

-cache

string

Cache type: inmemory, redis or memcache (default memcache).

-cache-inmemory-size

int

Maximum number of items in ARC cache (default 16384).

-cache-memcache-dns-cache-timeout

duration

DNS cache timeout (default 1m0s).

-cache-memcache-nodes

value

Comma-separated list of memcache shards (default 127.0.0.1:11211).

-cache-memcache-timeout

duration

Specifies read/write timeout (default 100ms).

-cache-redis-db

int

Database to be selected after connecting to the server.

-cache-redis-network

string

Network type, either tcp or unix (default tcp).

-cache-redis-nodes

value

Array of Host:Port addresses (default localhost:6379).

-cache-redis-password

string

Optional password. Must match the password specified in the requirepass server configuration option.

-cache-redis-timeout

duration

Specifies dial/read/write timeout (default 5s).

-config

string

Path to config file.

-config-template

Output config template and exit.

-debug

–

Enable debug logging.

-extraction-api-extraction-api

string

Extraction API address legacy argument – please switch to ‘url’.

-extraction-api-keepalive

duration

Keep-alive connection timeout (default 24h0m0s).

-extraction-api-max-idle-conns-per-host

int

Max idle keep-alive connections per host (default 20).

-extraction-api-timeouts-connect

duration

extraction-api-timeouts-connect (default 5s).

-extraction-api-timeouts-idle-connection

duration

extraction-api-timeouts-idle-connection (default 10s).

-extraction-api-timeouts-overall

duration

extraction-api-timeouts-overall (default 35s).

-extraction-api-timeouts-response-header

duration

extraction-api-timeouts-response-header (default 30s).

-extraction-api-trace

–

Enable HTTP tracing (extremely verbose, slows everything down considerably).

-extraction-api-url

string

Extraction API address (default http://127.0.0.1:18666).

-generate-openapi

–

Flag for generating openapi docs and exit.

-help

–

Print help information.

-limits-allow-return-facen

–

Allow returning raw feature vectors to detect responses if ?return_facen=true (v2) or ?return_emben=true (v3).

-limits-body-image-length

int

Maximum length of image supplied in request body (default 33554432).

-limits-deny-networks

string

Comma-separated list of subnets that are not allowed to fetch from (default 127.0.0.0/8,192.168.0.0/16,10.0.0.0/8,::1/128,fe00::/8).

-limits-url-length

int

Maximum supported url length in bytes (default 4096).

-listen

string

IP:port to listen on (default :18411).

-normalized-storage-enabled

–

Enables normalize saving (default true).

-normalized-storage-s3-access-key

string

Access key for the object storage.

-normalized-storage-s3-bucket-name

string

S3 storage bucket name.

-normalized-storage-s3-endpoint

string

S3 compatible object storage endpoint.

-normalized-storage-s3-operation-timeout

int

Storage operations (Get, Put, Delete) timeout in seconds (default 30).

-normalized-storage-s3-public-url

string

Storage public URL.

-normalized-storage-s3-region

string

Storage region.

-normalized-storage-s3-secret-access-key

string

Secret key for the object storage.

-normalized-storage-s3-secure

–

If true API requests will be secure (HTTPS), and insecure (HTTP) otherwise (default true).

-normalized-storage-webdav-keepalive

duration

Keep-alive connection timeout (default 24h0m0s).

-normalized-storage-webdav-max-idle-conns-per-host

int

Max idle keep-alive connections per host (default 20).

-normalized-storage-webdav-timeouts-connect

duration

normalized-storage-webdav-timeouts-connect (default 5s).

-normalized-storage-webdav-timeouts-idle-connection

duration

normalized-storage-webdav-timeouts-idle-connection (default 10s).

-normalized-storage-webdav-timeouts-overall

duration

normalized-storage-webdav-timeouts-overall (default 35s).

-normalized-storage-webdav-timeouts-response-header

duration

normalized-storage-webdav-timeouts-response-header (default 30s).

-normalized-storage-webdav-trace

–

Enable HTTP tracing (extremely verbose, slows everything down considerably).

-normalized-storage-webdav-upload-url

string

Webdav storage for normalized, disable normalized if empty string (default http://127.0.0.1:3333/uploads/).

-normalized_storage

string

Normalized storage type: webdav, s3 (default webdav).

-objects

value

Supported object types (default face,body,car).

-storage-api-cooldown

duration

Cooldown timeout after communication error (default 2s).

-storage-api-galleries-read-slave-first

Prefer slaves over master for get/list galleries requests.

-storage-api-keepalive

duration

Keep-alive connection timeout (default 24h0m0s).

-storage-api-max-idle-conns-per-host

int

Max idle keep-alive connections per host (default 20).

-storage-api-max-slave-attempts

int

Give up after trying to read from max_slave_attempts slaves (default 2).

-storage-api-read-slave-first

–

Prefer slaves over master for requests.

-storage-api-read-slave-only

–

Ignore master on read requests. If true: ReadSlaveFirst will be ignored.

-storage-api-timeouts-connect

duration

storage-api-timeouts-connect (default 5s).

-storage-api-timeouts-idle-connection

duration

storage-api-timeouts-idle-connection (default 10s).

-storage-api-timeouts-overall

duration

storage-api-timeouts-overall (default 35s).

-storage-api-timeouts-response-header

duration

storage-api-timeouts-response-header (default 30s).

-storage-api-trace

–

Enable HTTP tracing (extremely verbose, slows everything down considerably).

The format of environment variable for flag -my-flag is CFG_MY_FLAG.

Priority:

  1. Defaults from source code (lowest priority).

  2. Config file.

  3. Environment variables.

  4. Command line.