Tone Detection

The tone endpoint checks the tone for a given text. This is similar to our sentiment endpoint, but provides more fine-grained categories.

Try it out

The endpoint includes 28 tones (contact us) if you're looking for other tones).

admiring
amused
angry
annoyed
approving
aware
confident
confused
curious
eager
disappointed
disapproving
embarrassed
excited
fearful
grateful
joyful
loving
mournful
neutral (most common)
optimistic
relieved
remorseful
repulsed
sad
worried
surprised
sympathetic You can find definitions of these tones below.

The overall tone is returned as well as the tone for each sentence for a more fine-grained breakdown.

Tone POST

Sample Code

cURL
JavaScript
Python

curl -X POST https://api.sapling.ai/api/v1/tone \
     -H "Content-Type: application/json" \
     -d '{"key":"<api-key>", "text":"Really stoked about this! Will it be ready by next week?"}'

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/tone',
            {
                key: '<api-key>',
                text,
            },
        );
        const {status, data} = response;
        console.log({status});
        console.log(JSON.stringify(data, null, 4));
    } catch (err) {
        const { msg } = err.response.data;
        console.log({err: msg});
    }
}

run('Really stoked about this! Will it be ready by next week?');

import requests
from pprint import pprint

response = requests.post(
    "https://api.sapling.ai/api/v1/tone",
    json={
        "key": "<api-key>",
        "text": "Really stoked about this! Will it be ready by next week?"
    }
)

if 200 <= response.status_code < 300:
    pprint(response.json())
else:
    print('Error: ', response.status_code, response.text)

Sample Response

{
  "overall": [
    [ 0.9247264862060547, "curious", "🤓" ],
    [ 0.04547286033630371, "excited", "😀" ],
    [ 0.005686695221811533, "confused", "😕" ]
  ],
  "results": [
    [
      [ 0.9936646223068237, "excited", "😀" ],
      [ 0.001380942645482719, "admiring", "😲" ],
      [ 0.0009780488908290863, "joyful", "😂" ]
    ],
    [
      [ 0.5469484329223633, "confused", "😕" ],
      [ 0.39931708574295044, "curious", "🤓" ],
      [ 0.040689751505851746, "neutral", "😐" ]
    ]
  ],
  "sents": [
    "Really stoked about this!",
    "Will it be ready by next week?"
  ]
}

Request Parameters

https://api.sapling.ai/api/v1/tone

HTTP method: POST

The Tone API POST endpoint takes JSON parameters documented below:

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

text: String
Text to analyze the tone for.

Response Parameters

The tone endpoint contains three fields:

sents: The sentences the text contains.
overall: A list of tuples of the form (probability, tone, emoji).
results: For each sentence, a list item containing a list of tuples of the form (probability, tone, emoji).

Example output:

{
    "overall": [
        [
            0.9893065094947815,
            "neutral",
            "😐"
        ],
        [
            0.0055707162246108055,
            "curious",
            "🤓"
        ],
        [
            0.0030300025828182697,
            "confused",
            "😕"
        ]
    ],
    "results": [
        [
            [
                0.9893065094947815,
                "neutral",
                "😐"
            ],
            [
                0.0055707162246108055,
                "curious",
                "🤓"
            ],
            [
                0.0030300025828182697,
                "confused",
                "😕"
            ]
        ]
    ],
    "sents": [
        "Hi, how are you doing?"
    ]
}

Tone Descriptions and Examples

To clarify the differences between the different tones, we provide brief definitions and example(s) of each.

admiring: With respect and reverence, often used when expressing regard or affection for someone or something. You're amazing.
amused: Light-hearted and typically signaling laughter or enjoyment of a situation. Haha, go for it.
angry: Expresses strong displeasure or rage, often characterized by sharp, harsh or loud expressions. This is stupid.
annoyed: Conveys irritation or frustration, less intense than anger but often tinged with impatience. You're wasting my time.
approving: Suggests agreement or validation, usually conveying acceptance and positivity towards subject. That is a fitting match.
aware: Indicates an understanding or consciousness about the subject.
confident: Exudes certainty and assurance, often assertive and conveying belief. We're proud of this work.
confused: Conveys uncertainty or bewilderment, often with a lack of understanding or clarity about a situation. I have no idea what's going on.
curious: Questioning and often signaling an eagerness to learn or know more about something. Can you please tell me more?
eager: With enthusiasm and keenness, often characterized by anticipation or readiness to engage.
disappointed: Expresses a sense of letdown or dissatisfaction when expectations are not met. This is not as good as I expected.
disapproving: Conveys a negative judgment, criticism, or dissatisfaction towards a subject or action. This is not as good as it should be.
embarrassed: Shows feelings of self-consciousness, shame, or awkwardness, often after a mistake or awkward situation. I felt so self-conscious and awkward.
excited: Full of enthusiasm and anticipation, often showing high energy and eagerness about an event or idea. Looking forward to it!
fearful: Conveys apprehension, anxiety, or dread, often used when there's a perceived threat or danger. I'm scared to death.
grateful: Expresses appreciation or thankfulness, often for someone's actions or presence. Thank you so much.
joyful: Exudes happiness, delight, or pleasure, often full of positive energy and cheerfulness. What a beautiful day to be alive!
loving: Expresses affection, warmth, and tenderness, often used when expressing feelings of affection and care.
mournful: Reveals sorrow or grief, often used when lamenting a loss or a tragic event. I'm sorry for your loss.
neutral: Maintains an objective or impartial attitude; devoid of strong emotions or bias. We'll be there in 20 minutes.
optimistic: Conveys hopefulness and confidence about the outcome of something. The future is full of promise.
relieved: Conveys a sense of release from stress or worry, often following a resolution or good news. That makes me feel so much better.
remorseful: Expresses regret or guilt over a past action or event, often accompanied by a desire to make amends. I'm sorry about that.
repulsed: Conveys a strong aversion or disgust towards a subject or situation. Yuck, get it away!
sad: Expresses unhappiness, sorrow, or grief, generally less intense than mournful but still conveying a negative emotional state. I feel so miserable.
worried: Conveys unease or concern, often anticipating potential problems or negative outcomes.
surprised: Expresses shock or astonishment, usually as a result of an unexpected event or piece of information. Wow, that's so unexpected!
sympathetic: Shows understanding and compassion towards someone else's situation or feelings. I can only imagine what you're going through.

Tone POST​

Sample Code​

Sample Response​

Request Parameters​

Response Parameters​

Tone Descriptions and Examples​