Audio classification¶

POST /api/v5/audio/classification

Performs sentiment classification on an uploaded audio file and returns the audio vector representation, scores for the three sentiment dimensions (arousal, dominance, valence), and the formatted list of classification results.

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint allows anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`model`	query	string	Yes	Model name; defaults to `audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim`

The request body is a multipart/form-data form with the following fields:

Request Body:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "file": {
      "description": "Audio file (mp3, wav, m4a, flac, and webm are supported); required",
      "type": "string",
      "format": "binary"
    }
  },
  "required": ["file"]
}

Note: Although model is marked required, it falls back to the default model audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim when omitted.

Response parameters¶

Field	Type	Always returned	Nullable	Description
`vector`	number	Yes	Yes	Vector representation of the audio file
`emotion_class`	object	Yes	Yes	Scores for the three sentiment dimensions (arousal/dominance/valence)
`emotionItems`	array	Yes	Yes	List of sentiment classification results (formatted)

emotion_class object

Field	Type	Always returned	Nullable	Description
`emotion_class.arousal`	number	Yes	Yes	Arousal score (degree of emotional activation, such as excited or calm)
`emotion_class.dominance`	number	Yes	Yes	Dominance score (sense of emotional control, such as dominant or submissive)
`emotion_class.valence`	number	Yes	Yes	Valence score (positive or negative emotion, such as pleasant or unpleasant)

emotionItems array elements

Field	Type	Always returned	Nullable	Description
`emotionItems.label`	string	Yes	Yes	Classification name (localized), such as `Arousal`
`emotionItems.labelEn`	string	Yes	Yes	Classification name (English), such as `Arousal`
`emotionItems.value`	string	Yes	Yes	Numeric value, such as `0.6820112466812134`
`emotionItems.valueDesc`	string	Yes	Yes	Value description (localized), such as `slightly excited`
`emotionItems.valueDescEn`	string	Yes	Yes	Value description (English), such as `slightly excited`

Error response¶

400 invalid parameters:

{
  "error_message": "Failed to read file: <reason>"
}

401 unauthenticated:

{
  "error_message": "Missing or invalid access token"
}

500 service error:

{
  "error_message": "The audio transcription service returned an empty response"
}

The structure of the error response body follows the actual response; field names may differ because the upstream service varies.

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (Bad request)
`401`	Authentication required (Unauthorized)
`500`	Internal system error (Internal server error)

Request example¶

Parameter notes¶

Replace <file> with the path of the audio file (mp3, wav, m4a, flac, and webm are supported);
Replace <model> with the model name. It may be omitted, in which case the default model audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim is used;
This endpoint allows anonymous access, or you can send an AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/audio/classification' \
  -H 'Accept: application/json' \
  -F 'file=@<audio-file>' \
  -F 'model=audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim'

JavaScript¶

// Native fetch (Node.js 18+ / browsers)
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("model", "audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim");

const response = await fetch("https://api.atomgit.com/api/v5/audio/classification", {
  method: "POST",
  headers: {
    "Accept": "application/json",
  },
  body: formData,
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/audio/classification",
    headers={
        "Accept": "application/json",
    },
    files={
        "file": (
            "audio.mp3",
            open("audio.mp3", "rb"),
            "audio/mpeg",
        )
    },
    data={
        "model": "audeering/wav2vec2-large-robust-12-ft-emotion-msp-dim",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "vector": null,
  "emotion_class": {
    "arousal": 0.38037118315696716,
    "dominance": 0.4589272439479828,
    "valence": 0.5078083276748657
  },
  "emotion_items": [
    {
      "label": "Arousal",
      "label_en": "Arousal",
      "value": "0.38037118315696716",
      "value_desc": "Calm",
      "value_desc_en": "Calm"
    },
    {
      "label": "Valence",
      "label_en": "Valence",
      "value": "0.5078083276748657",
      "value_desc": "Neutral",
      "value_desc_en": "Neutral"
    },
    {
      "label": "Dominance",
      "label_en": "Dominance",
      "value": "0.4589272439479828",
      "value_desc": "Neutral",
      "value_desc_en": "Medium Control"
    }
  ]
}

Note: The response is the raw JSON returned by the upstream service. The actual field names (emotion_class/emotion_class, emotionItems/emotion_items) and key style follow the actual response.

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc