OpenAPI
openapi: "3.0.1"
info:
title: "bio-api"
description: "the Biomodality API enables multi-modal biometric verification in\
\ a single platform, starting with face and voice, with additional modalities\
\ coming soon."
contact:
name: "Biomodality, by Tefani"
email: "support@biomodality.com"
version: "2025-10-13T21:08:35Z"
servers:
- url: "https://api.biomodality.com"
paths:
/get_token:
post:
description: "accepts a length parameter (4 – 6) and returns a hyphen-separated\
\ token of the same length that complies with the validate_speech resource.\
\ You can use this resource to obtain example tokens and then generate similar\
\ ones locally for faster, more cost-efficient processing."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/gettoken"
required: true
responses:
"200":
description: "4-to-6 digit hyphen-separated token as a string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/compare_faces:
post:
description: "accepts two JPG (JPEG) or PNG images (up to 3 MB each), along\
\ with an optional cosine similarity threshold (0.4 – 0.8, defaults to 0.5),\
\ and returns the cosine similarity and match result between the two largest\
\ faces in the images. Cosine similarity threshold depends on how constrained\
\ the face capture process is and the desired balance between security and\
\ convenience for your application."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/comparefaces"
required: true
responses:
"200":
description: "cosine similarity and match result"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/encode_face:
post:
description: "accepts a JPG (JPEG) or PNG image (up to 3 MB), detects the largest\
\ face, and returns a 512-dimensional face embedding that can be used for\
\ verification or identification. Cosine similarity should be used as the\
\ comparison metric, with a recommended threshold range of 0.4 – 0.8, depending\
\ on how constrained the face capture process is and the desired balance between\
\ security and convenience for your application."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/encodeface"
required: true
responses:
"200":
description: "512-dimensional face embedding"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/compare_voices:
post:
description: "accepts two 16 kHz waveform audios (up to 10 seconds each), along\
\ with an optional cosine similarity threshold (0.1 – 0.5, defaults to 0.25),\
\ and returns the cosine similarity and match result between the two speakers\
\ in the audios. Cosine similarity threshold depends on whether it's used\
\ to compare text-dependent or text-independent audios, how constrained the\
\ voice capture process is, and the desired balance between security and convenience\
\ for your application."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/comparevoices"
required: true
responses:
"200":
description: "cosine similarity and match result"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/validate_speech:
post:
description: "accepts 16 kHz waveform audio (up to 10 seconds) and a 4-to-6\
\ digit token, extracts the spoken digits from the audio (110 language/region\
\ supported), and returns the Levenshtein distance between the extracted digits\
\ and the provided token. The Levenshtein distance measures the minimum number\
\ of single-digit insertions, deletions, or substitutions required to transform\
\ the extracted digits into the provided token. The length of the token and\
\ the acceptable Levenshtein distance depends on how constrained the voice\
\ capture process is and the desired balance between security and convenience\
\ for your application. For improved convenience, using longer tokens with\
\ some tolerance for the Levenshtein distance is recommended (e.g., 5-digit\
\ token with an acceptable Levenshtein distance of 1)."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/validatespeech"
required: true
responses:
"200":
description: "Levenshtein distance"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/check_usage:
post:
description: "accepts an optional number of days back parameter (0 – 90, defaults\
\ to 30) and returns details about the usage plan associated with the API\
\ key, along with daily usage. Please note that this resource is not intended\
\ for real-time usage checks. Actual usage data may take several minutes,\
\ and in some cases hours, to be reflected. It is more suitable for billing\
\ and reporting purposes."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/checkusage"
required: true
responses:
"200":
description: "usage plan details and daily usage for the specified period"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
/encode_voice:
post:
description: "accepts 16 kHz waveform audio (up to 10 seconds) and returns a\
\ 192-dimensional speaker embedding that can be used for verification or identification.\
\ Cosine similarity should be used as the comparison metric, with a recommended\
\ threshold range of 0.1 – 0.5, depending on whether it's used to compare\
\ text-dependent or text-independent audios, how constrained the voice capture\
\ process is, and the desired balance between security and convenience for\
\ your application."
parameters:
- name: "Content-Type"
in: "header"
required: true
schema:
type: "string"
- name: "x-api-key"
in: "header"
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/encodevoice"
required: true
responses:
"200":
description: "192-dimensional speaker embedding"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
security:
- api_key: []
components:
schemas:
comparevoices:
title: "comparevoices"
required:
- "payload_1"
- "payload_2"
type: "object"
properties:
payload_1:
required:
- "audio_data"
type: "object"
properties:
audio_data:
minLength: 1
type: "string"
description: "first base64 encoded waveform audio"
filename:
type: "string"
description: "optional filename of the first audio file"
additionalProperties: false
payload_2:
required:
- "audio_data"
type: "object"
properties:
audio_data:
minLength: 1
type: "string"
description: "second base64 encoded waveform audio"
filename:
type: "string"
description: "optional filename of the second audio file"
additionalProperties: false
cosine_similarity_threshold:
maximum: 0.5
minimum: 0.1
type: "number"
description: "optional threshold value for cosine similarity comparison,\
\ defaults to 0.25"
additionalProperties: false
Empty:
title: "Empty Schema"
type: "object"
encodevoice:
title: "encodevoice"
required:
- "audio_data"
type: "object"
properties:
audio_data:
minLength: 1
type: "string"
description: "base64 encoded waveform audio"
filename:
type: "string"
description: "optional filename of the audio file"
additionalProperties: false
gettoken:
title: "gettoken"
required:
- "length"
type: "object"
properties:
length:
maximum: 6
minimum: 4
type: "integer"
description: "number of digits of the token to be generated"
additionalProperties: false
checkusage:
title: "checkusage"
type: "object"
properties:
days_back:
maximum: 90
minimum: 0
type: "integer"
description: "number of days back, defaults to 30 days"
additionalProperties: false
validatespeech:
title: "validatespeech"
required:
- "audio_data"
- "language_code"
- "token"
type: "object"
properties:
audio_data:
minLength: 1
type: "string"
description: "base64 encoded waveform audio"
filename:
type: "string"
description: "optional filename of the audio file"
language_code:
type: "string"
description: "BCP 47 language tag"
enum:
- "af-ZA"
- "ar-DZ"
- "ar-BH"
- "ar-EG"
- "ar-IQ"
- "ar-IL"
- "ar-JO"
- "ar-KW"
- "ar-LB"
- "ar-MR"
- "ar-MA"
- "ar-OM"
- "ar-QA"
- "ar-SA"
- "ar-PS"
- "ar-SY"
- "ar-TN"
- "ar-AE"
- "ar-YE"
- "eu-ES"
- "bn-BD"
- "bs-BA"
- "bg-BG"
- "cmn-Hans-CN"
- "cmn-Hans-HK"
- "cmn-Hant-TW"
- "cs-CZ"
- "da-DK"
- "nl-BE"
- "nl-NL"
- "en-AU"
- "en-CA"
- "en-GH"
- "en-HK"
- "en-IN"
- "en-IE"
- "en-KE"
- "en-NZ"
- "en-NG"
- "en-PK"
- "en-PH"
- "en-SG"
- "en-ZA"
- "en-TZ"
- "en-GB"
- "en-US"
- "et-EE"
- "fil-PH"
- "fi-FI"
- "fr-BE"
- "fr-CA"
- "fr-FR"
- "fr-CH"
- "de-AT"
- "de-DE"
- "de-CH"
- "el-GR"
- "hi-IN"
- "hu-HU"
- "id-ID"
- "it-IT"
- "it-CH"
- "ja-JP"
- "kn-IN"
- "ko-KR"
- "lv-LV"
- "lt-LT"
- "ms-MY"
- "ml-IN"
- "mr-IN"
- "no-NO"
- "fa-IR"
- "pl-PL"
- "pt-BR"
- "pt-PT"
- "ro-RO"
- "ru-RU"
- "sr-RS"
- "si-LK"
- "sk-SK"
- "es-AR"
- "es-BO"
- "es-CL"
- "es-CO"
- "es-CR"
- "es-DO"
- "es-EC"
- "es-SV"
- "es-GT"
- "es-HN"
- "es-MX"
- "es-NI"
- "es-PA"
- "es-PE"
- "es-PR"
- "es-ES"
- "es-US"
- "es-UY"
- "es-VE"
- "sv-SE"
- "ta-IN"
- "ta-MY"
- "ta-SG"
- "ta-LK"
- "te-IN"
- "th-TH"
- "tr-TR"
- "uk-UA"
- "vi-VN"
- "zu-ZA"
token:
maxLength: 11
minLength: 7
type: "string"
description: "4-to-6 digit hyphen-separated token"
additionalProperties: false
encodeface:
title: "encodeface"
required:
- "image_data"
type: "object"
properties:
image_data:
minLength: 1
type: "string"
description: "base64 encoded jpg (jpeg) or png image"
filename:
type: "string"
description: "optional filename of the image"
additionalProperties: false
comparefaces:
title: "comparefaces"
required:
- "payload_1"
- "payload_2"
type: "object"
properties:
payload_1:
required:
- "image_data"
type: "object"
properties:
image_data:
minLength: 1
type: "string"
description: "first base64 encoded jpg (jpeg) or png image"
filename:
type: "string"
description: "optional filename of the first image"
additionalProperties: false
payload_2:
required:
- "image_data"
type: "object"
properties:
image_data:
minLength: 1
type: "string"
description: "second base64 encoded jpg (jpeg) or png image"
filename:
type: "string"
description: "optional filename of the second image"
additionalProperties: false
cosine_similarity_threshold:
maximum: 0.8
minimum: 0.4
type: "number"
description: "optional threshold value for cosine similarity comparison,\
\ defaults to 0.5"
additionalProperties: false
securitySchemes:
api_key:
type: "apiKey"
name: "x-api-key"
in: "header"