Cochl.Sense API allows to detect what is contained inside sound data. Send audio data over the internet to discover what it contains.

npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o python-client

v1.1.0 Download specification

Authentication

API_Key

We use a simple API key to authenticate requests on the backend. API keys are scoped to a given project. To get an API key, go to the dashboard projects page. One key is available for each project. If no projects are present, create one by clicking “add new project” allows creating a new project.

Once the key is retrieved, it will be required to be passed in the HTTP request headers x-api-key: YOUR_API_KEY

Audio Session

Sense API Audio Session is the heart of the API. An audio session represents one audio source that will be inferenced*. An audio source can be either a file or a stream.

*inferenced: analyzed by our deep learning neural network

Lifetime

An audio session goes through 3 states during its lifetime :

writable -> readonly -> deleted

• The chunk can be uploaded if and only if session is writable
• Status can be readonly if and only if session is not deleted

A state can become readonly

• By manually updating the session with a PATCH request
• When an error occurs
• When session total_size has been reached

A state can become deleted.

• By manually deleting session with a DELETE request
• When the session becomes inactive*

*inactive: a session is considered inactive if no chunks have been uploaded for more than one hour

Upload

Audio needs to be sent to the server by chunk. The maximum allowed size of a chunk is 1MiB (1MiB == 1024KiB)

• For a stream, we recommend sending half second long audio chunk. This allows having the shortest latency between audio recording and inferenced results.
• For a file, we recommend sending a file by chunk of 1MiB audio chunks.

One big difference between stream and file is how they are decoded. For a stream, we recommend every chunk is required to be decodable*, whereas, for a file, the concatenation of all the chunks needs to be decodable.

*decodable: an audio source is decodable if by having only the content-type and the raw data, it is possible to decode the audio

Inference

Once chunks are received, our server will begin to inference automatically.

• For a stream, chunks are inferenced immediately
• For a file, chunks are inferenced when session state becomes readonly

Status

Inference results can be retrieved on the status endpoint.

To get all results of a given session, it is recommended to use next_token. It gives the warranty to read all results incorrect order exactly once.

Note: In the future, results from the deleted audio session will be accessible on another endpoint

Error

In case an error occurs during a session, that session will become readonly and pending inferences of chunks are canceled. An error message will be available in the session status.

A typical error is a content-type decoding error. For instance, audio/wav data may have been misclassified as audio/mp3 data.

Create Session

POST /audio_sessions/

Create a new session. An API key is required. Session parameters are immutable and can be set at creation only.

Authorization

• API_Key

Request Body

Responses

Delete Session

DELETE /audio_sessions/{session_id}

Change the state of the session to deleted. All future call on the session will return 404

Params

Responses

Update Session

PATCH /audio_sessions/{session_id}

Update a session

Params

Request Body

Responses

Upload Chunk

PUT /audio_sessions/{session_id}/chunks/{chunk_sequence}

Upload new audio chunk

Params

Request Body

Responses

Read Status

GET /audio_sessions/{session_id}/status

Get session status

Note that if all chunks didn’t finish to be inferenced, the server will wait for at least one result to be available in the required page range before returning result. Such waiting can lead to HTTP requests timeout. Therefore we recommend implementing a client retry logic.

Params

Responses

Schemas

AudioChunk

AudioContentType

AudioMetadata

AudioType

possible values

• stream

• file

CreateSession

GenericError

Page

Sense

SenseEvent

SenseEventTag

SessionRefs

SessionStatus

UpdateSession