Speaker Diarization: start task

POST 
/api/technology/speaker-diarization

Start a Speaker Diarization task for a media file.

Speaker Diarization features

• Multi-channel media files are supported.
• For each channel an independent Speaker Diarization result is produced.
• Speaker Diarization can be configured by two mutually exclusive parameters max_speakers and total speakers, therefore, only one of them can be used at a time.
• The parameter max_speakers is the upper boundary for the number of speakers that are believed to be speaking in the media file.
• The parameter total_speakers is the exact number of speakers that are believed to be speaking in the media file. If set, the Speaker Diarization result will contain this number of speakers.
• Processing can be limited to a specific time segment in the media file with query parameters.

Request

Query Parameters

channel_mode Channel Mode

Possible values: [split, mix]

Default value: split

A string enumeration value representing the channel mode for conversion. This value indicates how the audio channels should be processed during conversion. Only the channels with the specified indices (channels parameter) will be processed, and others will be ignored.

channels Channels

A string of integers separated by comma (without spaces), representing the channels that should be kept during conversion. If specified, only the channels with the specified indices will be processed, and others will be ignored. If empty, all channels in the audio data will be processed. Note that channels is 0-based.

range_from Range From

Default value: 0

Specifies the time in the input file where processing starts. If the parameter equals 0 (the default value), the recording is processed from the beginning. Time is given in seconds.

range_to Range To

Specifies the time in the file where processing ends. If the parameter is not specified, the input file is processed to the end. Time is given in seconds.

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 request and response combination throughout all components of a distributed system. Request ID will be generated if not provided.

multipart/form-data

Body

required

file binaryrequired

Input media file.

config

object

Optional configuration for Speaker Diarization.

max_speakers

object

anyOf

MOD1

Specifies the upper boundary of speakers that can be detected during diarization. If no value is set, the technology uses the default value of 100. This parameter is mutually exclusive with total_speakers, and using both results in an error.

integer

Possible values: > 0

total_speakers

object

anyOf

MOD1

Specifies the exact number of speakers that can be detected during diarization. This parameter is mutually exclusive with max_speakers, and using both results in an error.

integer

Possible values: > 0

Responses

202

Speaker Diarization task was accepted. Follow the X-Location header to poll for the task state.

Response Headers

• X-Location

  string

  Example: /api/technology/speaker-diarization/123e4567-e89b-12d3-a456-426614174000

  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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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": {}
    }
  ]
}

413

The request entity (payload) size exceeds the allowed limit.

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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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.size-limit-exceeded

Request size limit exceeded.

{
  "type": "request.size-limit-exceeded",
  "message": "Request size limit exceeded.",
  "detail": [
    {
      "location": [
        "body",
        "file"
      ],
      "message": "Input media file too large.",
      "type": "media.too-large",
      "context": {
        "file_size": 1048576000,
        "max_file_size": 524288000,
        "size_unit": "bytes"
      }
    }
  ]
}

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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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

  Size of the current rate limiting window.

• x-ratelimit-remaining

  number

  Remaining number of requests in the current 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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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": []
}

507

The storage is full and cannot accept any data.

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]

Machine-readable error type.

message Message (string)required

Human-readable summary of the error.

detail

object[]

Optional higher level of detail. 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": {}
    }
  ]
}

insufficient storage

Storage capacity exceeded.

{
  "type": "storage.capacity-exceeded",
  "message": "Storage capacity exceeded.",
  "detail": []
}

Loading...