Rephrase

The Paraphrase and Rephrase endpoints offer paraphrasing for particular styles. Given an input sentence, the endpoint returns output sentences that preserve meaning but use alternative phrasings or styles.

Try it out

Note that while the paraphrases/rephrases retain the same general meaning, they vary in how much they differ from the input sentence. Put another way, while the syntax and terminology of the input may change, the semantics should be preserved.

Rephrase POST

In addition to the paraphrase endpoint, the rephrase endpoint also offers a few style transformations:

• Informal to Formal (informal_to_formal): Given a casual/informal input text, generate a more formal/professional output. You can test the endpoint here.
• Passive to Active (passive_to_active): Generate sentence in active voice given sentence in passive voice. You can test the endpoint here.
• Shorten (shorten): Rewrite text to about half its length while preserving its meaning and tone. You can test the endpoint here.
• Split (sentence_split): Given a long/convoluted sentence, split it into two sentences. You can test the endpoint here.
• Short to Long / Expand (expand): Given some text, provide a longer version of the text while trying to (mostly) preserve the same meaning. You can test the endpoint here.

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

HTTP method: POST

Sample Code

cURL

curl -X POST https://api.sapling.ai/api/v1/rephrase \
     -H "Content-Type: application/json" \
     -d '{
        "key":"<api-key>",
        "text":"hey wuts going on",
        "mapping":"informal_to_formal"
    }'

JavaScript

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/rephrase',
            {
                key: '<api-key>',
                text,
                mapping:'informal_to_formal'
            },
        );
        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('hey wuts going on');

Python

import requests
from pprint import pprint

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/rephrase'

data = {
    'key': key,
    'text': 'hey wuts going on',
    'mapping':'informal_to_formal'
}

try:
    response = requests.post(url, json=data)
    if 200 <= response.status_code < 300:
      resp_json = response.json()
      results = resp_json['results']
      pprint(results)
    else:
      print('Error: ', str(response.status_code), response.text)
except Exception as e:
    print('Error: ', e)

Sample Response

{
  "results": [
    {
      "hash": "5c09974f-3fae-560d-9982-ba3ff7087fff",
      "model_version": "v20220514",
      "original": "hey wuts going on",
      "rephrase_type": "informal_to_formal",
      "replacement": "What is going on, please?"
    },
    {
      "hash": "e8392c8f-c190-58df-84ef-887a29a78d2c",
      "model_version": "v20220514",
      "original": "hey wuts going on",
      "rephrase_type": "informal_to_formal",
      "replacement": "I am unaware of what is going on."
    },
    {
      "hash": "e4dd013c-e79c-5031-ab74-4614703c3f16",
      "model_version": "v20220514",
      "original": "hey wuts going on",
      "rephrase_type": "informal_to_formal",
      "replacement": "What is going on?"
    },
    {
      "hash": "8b593139-7353-50a9-8c99-e59a82d16031",
      "model_version": "v20220514",
      "original": "hey wuts going on",
      "rephrase_type": "informal_to_formal",
      "replacement": "Hey, what is happening?"
    }
  ]
}

Request Parameters

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
Input query to rephrase. Current maximum length is 4,000 characters. Contact us if you need support for longer inputs.

mapping String
The model to use. Available models include paraphrase, informal_to_formal, passive_to_active, active_to_passive, sentence_split, expand, and shorten. Additionally, there are switch_tone and switch_tense options, where tone_mapping or tense_mapping should also be specified, respectively.

tone_mapping String
If mapping is set to switch_tone, then tone_mapping will be used for the target tone. Available options include: straightforward, professional, casual, confident, friendly, empathetic, diplomatic, and persuasive. Please contact us if you want additional tones to be added.

tense_mapping String
If mapping is set to switch_tense, then tense_mapping will be used for the target tense. Please contact us for the list of supported tenses.

Unsupported mapping, tone_mapping, and tense_mapping values return 400 Bad Request.

num_results: Integer
Number of results to return (currently only available for paraphrase). The minimum is 1. The maximum is 8. Contact us if you need additional results.

diversity: Float [Coming soon]
Ranges from 0 to 1. 0 means to not encourage diversity beyond the usual sampling. 1 means to make the outputs as diverse as possible (while still preserving semantics).

Response Parameters

results: JSON, array of rephrases.

Paraphrase POST

DEPRECATED Please instead use the Rephrase endpoint with mapping set to paraphrase.

The paraphrase endpoint provides alternative phrasings of an input text while preserving meaning and intent. An example input might be: "How are you?" with the output paraphrases, "How's it going?", "What's up?", and "How are you doing?".

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

HTTP method: POST

Sample Code

cURL

curl -X POST https://api.sapling.ai/api/v1/paraphrase \
     -H "Content-Type: application/json" \
     -d '{
        "key":"<api-key>",
        "text":"How are you?",
    }'

JavaScript

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/paraphrase',
            {
                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('How are you?');

Python

import requests
from pprint import pprint

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/paraphrase'

data = {
    'key': key,
    'text': 'How are you?',
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
      resp_json = resp.json()
      results = resp_json['results']
      pprint(results)
    else:
      print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

Sample Response

{
  "results": [
    {
      "hash": "26d70b5b-333f-52f2-9abe-7bdac7dfe95f",
      "model_version": "v20230414",
      "original": "How are you?",
      "rephrase_type": "paraphrase",
      "replacement": "What is your current state of affairs?"
    },
    {
      "hash": "9db4d831-f526-5ee3-b43a-f4ad02c0e2fa",
      "model_version": "v20230414",
      "original": "How are you?",
      "rephrase_type": "paraphrase",
      "replacement": "How are you doing?"
    },
    {
      "hash": "0f100133-1b07-5157-b61e-d25d13cdfa27",
      "model_version": "v20230414",
      "original": "How are you?",
      "rephrase_type": "paraphrase",
      "replacement": "What's your current state of affairs?"
    }
  ]
}

Request Parameters

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
Input query to paraphrase.

diversity: Float [Coming soon]
Ranges from 0 to 1. 0 means to not encourage diversity beyond the usual sampling. 1 means to make the outputs as diverse as possible (while still preserving semantics).

num_results: Integer [Coming soon]
Number of results to return. The minimum is 1. The maximum will depend on other settings, but is generally around 8. Contact us if you need additional results. Additional results will incur additional costs.

Response Parameters

results: JSON, array of paraphrases.