Object reference

The following class initialization docstrings should give you an idea of the objects that are used in the API7 Python package.

APIError

An exception that may be raised when interacting with the backend.

from API7.api_error import APIError

class APIError(Exception):
    """Class that defines an API Error
    :param http_status_code: the HTTP status code of the error
    :type int
    :param err_code: the API7 error code
    :type str
    :param messsage: the API7 error message
    :type str
    :param retry_after: if present, specifies the time 
        in seconds when the request can be retried to meet rate limit checks
    :type Union[int, None]
    """

APIDataValidationError

An exception that may be raised when interacting with the backend and using a field value that is invalid.

from API7.api_error import APIDataValidationError

class APIDataValidationError(Exception):
    """Class that defines an API Data Validation Error
    :param details: Error details from API Server
    :type dict
    """

SortOrder

An enum specifying the sort order

from API7.schemas import SortOrder

class SortOrder(enum.Enum):
    '''Sort order of collections'''
    ASC = "ASC"
    DESC = "DESC"

CollectionBase

An object to create a Collection

from API7.collections.schemas import CollectionBase

class CollectionBase:
    '''A minimal collection object for creation

    :param name: the name of the collection
    :type name:str
    :param description: the description of the collection
    :type description: str
    '''

Collection

An object representing a previously created Collection

from API7.collections.schemas import Collection

class Collection(CollectionBase):
    '''A previously created collection object

    :param id: the id of a previously created collection
    :type id:str
    :param name: the name of the collection
    :type name:str
    :param description: the description of the collection
    :type description: str
    :param count: the number of persons in this collection
    :type count: int
    :param create_date: date that this collection was created
    :type create_date: datetime
    :param modified_date: date that this collection was modified
    :type modified_date: datetime
    '''

CollectionList

An object representing a list of collections matching specifying paging and search criteria

from API7.collections.schemas import CollectionList

class CollectionList:
    '''A list of collections

    :param count: the total count of all collections in the database
    :type count:int
    :param collections: the collections matching the criteria
    :type collections:List[Collection]
    '''

PersonBase

An object to create a Person

from API7.persons.schemas import PersonBase

class PersonBase:
    '''A person object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[np.ndarray, str, Image, Path]]
    :param id: a unique identifier for the person. 
        If unspecified a new id will be generated, defaults to None
    :type id: Optional[str]
    :param name: the name of the person
    :type name:Optional[str]
    :param gender: the gender of the person, defaults to None
    :type gender: Optional[PersonGender]
    :param date_of_birth: the date of birth of the person, defaults to None
    :type date_of_birth: Optional[datetime]
    :param nationality: the nationality of the person, defaults to None
    :type nationality: Optional[str]
    :param collections: a list containing either Collection, 
        CollectionBase objects, or strings representing the 
        id of the collections that this person belongs to, 
        defaults to empty list []
    :type collections: Optional[List[Union[Collection, CollectionBase, str]]]
    :param notes: any additional notes about the person, defaults to None
    :type notes: Optional[str]
    :param is_bulk_insert: whether this person is part of a 
        bulk insert batch, defaults to False
    :type is_bulk_insert: Optional[bool]
    '''

Person

An object representing a previously created Person

from API7.persons.schemas import Person

class Person(PersonBase):
    '''A previously created person object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param id: a unique identifier for the person.
    :type id: Optional[str]
    :param name: the name of the person
    :type name:Optional[str]
    :param gender: the gender of the person, defaults to None
    :type gender: Optional[PersonGender]
    :param date_of_birth: the date of birth of the person, defaults to None
    :type date_of_birth: Optional[datetime]
    :param nationality: the nationality of the person, defaults to None
    :type nationality: Optional[str]
    :param collections: a list containing either Collection, 
        CollectionBase objects, or strings representing the 
        id of the collections that this person belongs to, 
        defaults to empty list []
    :type collections: Optional[List[Union[Collection, CollectionBase, str]]]
    :param notes: any additional notes about the person, defaults to None
    :type notes: Optional[str]
    :param is_bulk_insert: whether this person is part of a 
        bulk insert batch, defaults to False
    :type is_bulk_insert: Optional[bool]
    :param create_date: date that this person was created
    :type create_date: datetime
    :param modified_date: date that this person was modified
    :type modified_date: datetime
    '''

PersonList

An object representing a list of collections matching specifying paging and search criteria

from API7.persons.schemas import PersonList

class PersonList:
    '''A list of persons

    :param count: the total count of all persons in the database
    :type count:int
    :param persons: the persons matching the criteria
    :type persons:List[Person]
    '''

SearchMode

An enum specifying search mode

from API7.search.schemas import SearchMode

class SearchMode(enum.Enum):
    ACCURATE = 'ACCURATE'
    FAST = 'FAST'

SearchRequest

An object specifying a search request

from API7.search.schemas import SearchRequest

class SearchRequest:
    """A search request object

    :param collection_id: the collection id to restrict the search
    :type collection_id:str
    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param min_score: a minimum score to match the person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the model to search FAST or ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    """

PersonSearchResult

An item in a search response

from API7.search.schemas import PersonSearchResult

class PersonSearchResult:
    '''A Person and an associated similarity score

    :param person: the person
    :type person: Person
    :param score: the similarity score
    :type score: float
    '''

SearchOptions

Options for a search

from API7.search.schemas import SearchOptions

class SearchOptions:
    '''Class to specify search options

    :param collection_id: the collection id to restrict the search
    :type collection_id: str
    :param min_score: a minimum score to optionally search 
        for a person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the mode to use for the SearchMode.FAST 
        or SearchMode.ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    '''

DetectionRequest

An object specifying a detection request

from API7.search.schemas import DetectionRequest

class DetectionRequest:
    '''A detect object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type image: Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]
    :param search_options: optional search options, defaults to None. 
        If not specified, the search will not be performed
    :type search_options: SearchOptions
    '''

Box

An object specifying a bounding box in a detection response item

from API7.search.schemas import Box

class Box:
    '''A bounding box

    :param left: left ordinate
    :type left: int
    :param top: top ordinate
    :type top: int
    :param right: right ordinate
    :type right: int
    :param bottom: bottom ordinate
    :type bottom: int
    '''

Coordinate

An object specifying x and y coordinates

from API7.search.schemas import Coordinate

class Coordinate:
    '''A coordinate

    :param x: x ordinate
    :type x: int
    :param y: y ordinate
    :type y: int
    '''

Landmarks

An object specifying facial landmarks

from API7.search.schemas import Landmarks

class Landmarks:
    '''Landmarks of a face

    :param left_eye: left eye
    :type left_eye: Coordinate
    :param right_eye: right eye
    :type right_eye: Coordinate
    :param nose: nose
    :type nose: Coordinate
    :param left_mouth: left mouth
    :type left_mouth: Coordinate
    :param right_mouth: right mouth
    :type right_mouth: Coordinate
    '''

DetectionResponseItem

A single item in the list of items returned when calling the detect API

from API7.search.schemas import DetectionResponseItem

class DetectionResponseItem:
    '''A detection response item (one face) of a detection response
    which consists of a bounding box, landmarks, thumbnail, 
    detection score, and list of matching persons

    :param box: bounding box
    :type box: Box
    :param landmarks: landmarks
    :type landmarks: Landmarks
    :param thumbnail: thumbnail
    :type thumbnail: Image
    :param score: detection score
    :type score: float
    :param persons: list of matching persons
    :type persons: List[PersonSearchResult]
    '''

VerificationRequest

A object specifying a verification request

from API7.search.schemas import VerificationRequest

class VerificationRequest:
    '''A verification request object

    :param id: the id of a person being verified
    :type id:str
    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param min_score: a minimum score to match the person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the model to search FAST or ACCURATE, defaults to ACCURATE
    :type search_mode: Optional[SearchMode]
    '''

VerificationResponse

An object specifying a verification response

from API7.search.schemas import VerificationResponse

class VerificationResponse:
    '''A verification response object

    :param person: the person being verified
    :type person: Person
    :param score: the score of the verification
    :type score: float
    '''

DeviceType

An enum representing the type of image capture device for liveness analysis

from API7.liveness.schemas import DeviceType

class DeviceType(enum.Enum):
    DESKTOP = 'DESKTOP'
    ANDROID = 'ANDROID'
    IOS = 'IOS'

LivenessRequest

An object specifying a liveness request

from API7.liveness.schemas import LivenessRequest

class LivenessRequest:
    '''A liveness request object

    :param os: OS setting to choose being either DeviceType.DESKTOP, 
        DeviceType.ANDROID, or DeviceType.IOS
    :type os: Optional[DeviceType]
    :param image: image being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image 
        (obtained with PIL.Image.open()), or a pathlib path
    :type image: Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]
    '''

LivenessResponse

An object specifying a liveness response

from API7.liveness.schemas import LivenessResponse

class LivenessResponse:
    '''A liveness response object

    :param score: the score of the liveness
    :type score: float
    '''

CompareRequest

from API7.compare.schemas import CompareRequest

class CompareRequest:
    '''A compare request object

    :param gallery: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type gallery: List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param probe: another list of images (like gallery)
    :type probe: List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param search_mode: the model to search FAST or ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    '''