Voiceprint Comparison: start task

POST 
/api/technology/speaker-identification-voiceprint-comparison

Start voiceprint comparison task for two voiceprint lists.

The voiceprint lists are provided in the voiceprints_a and voiceprints_b parameters. The size of the lists must meet the following criteria:

• There must be at least one voiceprint in each list.
• The size of each list must not exceed the limit for maximum length, which defaults to 50,000.
• The product of the two list sizes must not exceed the limit for maximum voiceprint matrix size, which defaults to 1,000,000 (e.g., possible maximum list lengths include len(voiceprints_a)=1_000, len(voiceprints_b)=1_000 and len(voiceprints_a)=50_000, len(voiceprints_b)=20).

Each voiceprint is expected to be a Base64-encoded string.

How a voiceprint comparison request is arranged

See Voiceprint comparison task result documentation for details on how the result is arranged.

The request consists of two voiceprint lists arranged as columns and rows of the resulting score matrix.

As a result, all voiceprints from the columns list will be compared to all voiceprints in the rows list. The resulting scores will be filled in a matrix of (sizeof(voiceprints_a), sizeof(voiceprints_b)) dimensions.

For example, the following input:

{
  "voiceprints_a": ["vp_a_1", "vp_a_2", "vp_a_3"],
  "voiceprints_b": ["vp_b_1", "vp_b_2", "vp_b_3"]
}

encodes the following empty voiceprint comparison score input matrix:

		voiceprints_a list
		vp_a_1	vp_a_2	vp_a_3
voiceprints_b list	vp_b_1
	vp_b_2
	vp_b_3

The voiceprint comparison technology will then fill in the empty cells with scores.

Request

Header Parameters

x-correlation-id X-Correlation-Id

Correlation ID is a special type of request ID which is unique over a series of requests and responses, identifying a transaction in a distributed system. Correlation ID will be generated if not provided.

x-request-id X-Request-Id

In distributed system architecture (microservices architecture) it is a unique ID of a request and response combination throughout all components of the system. Request ID will be generated if not provided.

application/json

Body

required

voiceprints_a base64[]required

Possible values: >= 1

List A of Base64-encoded voiceprints to compare.

voiceprints_b base64[]required

Possible values: >= 1

List B of Base64-encoded voiceprints to compare.

Responses

202

Voiceprint comparison task was accepted. Follow the X-Location header to poll for the task state.

Response Headers

• X-Location

  string

  Example: /api/technology/speaker-identification-voiceprint-comparison/651f10f1-3025-41e7-ad4f-d4ae385c8b7d

  A URL the client should poll for task state and result.

application/json

Schema

Schema

task

object

required

task_id uuidrequired

state TaskInfoState (string)required

Possible values: [pending, running, rejected, failed, done]

Example (from schema)

{
  "task": {
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "state": "pending"
  }
}

400

Request payload data was invalid and could not be parsed.

application/json

Schema

Schema

type RequestErrorType (string)required

Possible values: [internal, resource.not-found, method.invalid, request.forbidden, request.invalid, request.validation-error, request.rate-limit-exceeded, request.size-limit-exceeded, storage.capacity-exceeded]

Types of errors that can occur during request handling.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional detail of the error. It is intended for better understanding of the error or advanced error handling.

Array [

location

object[]

required

Location of the error.

Array [

anyOf

MOD1

integer

MOD2

string

]

message Message (string)required

Human-readable summary of the error.

type Type (string)required

Machine-readable error type.

context

object

Optional key-value object with additional context

property name*

object

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

MOD5

Array [

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

]

]

Example (from schema)

{
  "type": "internal",
  "message": "string",
  "detail": [
    {
      "location": [
        0,
        "string"
      ],
      "message": "string",
      "type": "string",
      "context": {}
    }
  ]
}

request.invalid

Invalid request.

{
  "type": "request.invalid",
  "message": "Invalid request.",
  "detail": []
}

403

Request is forbidden.

application/json

Schema

Schema

type RequestErrorType (string)required

Possible values: [internal, resource.not-found, method.invalid, request.forbidden, request.invalid, request.validation-error, request.rate-limit-exceeded, request.size-limit-exceeded, storage.capacity-exceeded]

Types of errors that can occur during request handling.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional detail of the error. It is intended for better understanding of the error or advanced error handling.

Array [

location

object[]

required

Location of the error.

Array [

anyOf

MOD1

integer

MOD2

string

]

message Message (string)required

Human-readable summary of the error.

type Type (string)required

Machine-readable error type.

context

object

Optional key-value object with additional context

property name*

object

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

MOD5

Array [

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

]

]

Example (from schema)

{
  "type": "internal",
  "message": "string",
  "detail": [
    {
      "location": [
        0,
        "string"
      ],
      "message": "string",
      "type": "string",
      "context": {}
    }
  ]
}

request.forbidden

Processing capacity allowed for the operation was exceeded.

{
  "type": "request.forbidden",
  "message": "Request is forbidden.",
  "detail": [
    {
      "location": [
        "license"
      ],
      "message": "Licensed processing capacity exceeded.",
      "type": "licensing.capacity-exceeded",
      "context": {}
    }
  ]
}

422

Error during validation of request payload data occurred.

application/json

Schema

Schema

type RequestErrorType (string)required

Possible values: [internal, resource.not-found, method.invalid, request.forbidden, request.invalid, request.validation-error, request.rate-limit-exceeded, request.size-limit-exceeded, storage.capacity-exceeded]

Types of errors that can occur during request handling.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional detail of the error. It is intended for better understanding of the error or advanced error handling.

Array [

location

object[]

required

Location of the error.

Array [

anyOf

MOD1

integer

MOD2

string

]

message Message (string)required

Human-readable summary of the error.

type Type (string)required

Machine-readable error type.

context

object

Optional key-value object with additional context

property name*

object

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

MOD5

Array [

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

]

]

Example (from schema)

{
  "type": "internal",
  "message": "string",
  "detail": [
    {
      "location": [
        0,
        "string"
      ],
      "message": "string",
      "type": "string",
      "context": {}
    }
  ]
}

request validation error

Request validation error.

{
  "type": "request.validation-error",
  "message": "Request validation error.",
  "detail": []
}

429

Request rate limit exceeded.

The request may be retried after a while. The following response headers may be checked for details: retry-after, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.

Response Headers

• retry-after

  number

  Header indicates how long the user agent should wait before making a follow-up request.

• x-ratelimit-limit

  number

  Maximum number of requests which is allowed in the currently used rate limiting window.

• x-ratelimit-remaining

  number

  Remaining number of requests in the currently used rate limiting window.

• x-ratelimit-reset

  number

  Time at which the current rate limiting window resets (in UTC epoch).

application/json

Schema

Schema

type RequestErrorType (string)required

Possible values: [internal, resource.not-found, method.invalid, request.forbidden, request.invalid, request.validation-error, request.rate-limit-exceeded, request.size-limit-exceeded, storage.capacity-exceeded]

Types of errors that can occur during request handling.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional detail of the error. It is intended for better understanding of the error or advanced error handling.

Array [

location

object[]

required

Location of the error.

Array [

anyOf

MOD1

integer

MOD2

string

]

message Message (string)required

Human-readable summary of the error.

type Type (string)required

Machine-readable error type.

context

object

Optional key-value object with additional context

property name*

object

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

MOD5

Array [

anyOf

MOD1

string

MOD2

integer

MOD3

number

MOD4

boolean

]

]

Example (from schema)

{
  "type": "internal",
  "message": "string",
  "detail": [
    {
      "location": [
        0,
        "string"
      ],
      "message": "string",
      "type": "string",
      "context": {}
    }
  ]
}

request.rate-limit-exceeded

Rate limit exceeded.

{
  "type": "request.rate-limit-exceeded",
  "message": "Rate limit exceeded: 1 per 5 second.",
  "detail": []
}

Loading...