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
• embarassed
• 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

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?"}'

JavaScript

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?');

Python

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?"
    }
)

pprint(response.json())

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.

text: String
Text to analyze the tone for.

Response Parameters

The tone endpoint contains three fields:

1. sents: The sentences the text contains.
2. overall: A list of tuples of the form (probability, tone, emoji).
3. 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.