Paraphrase

AI21 Studio's /paraphrase API offers access to our world-class paraphrasing engine. It has been specifically developed for suggesting alternative ways to convey the same message using different words. This is also the engine behind Wordtune - our award winning writing assistant, so you know it's pretty awesome.

Don’t just take our word for it, give it a go! 💫

Whether you're an NLP enthusiast or have no prior knowledge, this API is for you. There are many clever mechanisms under the hood, but you don't have to understand them (if you don't want to). As a paraphrase-specific API, you can easily integrate it into your systems and get top-notch paraphrasing in a matter of minutes, with no prompt engineering required. Additionally, since it's optimized for this purpose, it's significantly more efficient than building it from scratch, and an order of magnitude cheaper.

This API takes a piece of text and returns a list of paraphrases that convey the same meaning using different words. As a specialized API for paraphrasing, it contains features to enable you more control over the output by adjusting the tone and style. Moreover, you can add additional context to the text, to make the rewrite suggestion more relevant (by paraphrasing a certain range of your text).

Features

Choose a style that fits your needs

You have the choice between five different styles:

General - there are fresh and creative ways to rephrase sentences. Offer them to your users.
Casual - convey a friendlier and more accessible tone for the right audience.
Formal - present your words in a more professional way.
Short - express your messages clearly and concisely.
Long - expand your sentences to give more detail, nuance and depth.

Adding context to the paraphrase

You can paraphrase only part of the text while keeping the surrounding text unchanged by specifying a range within the text.

BAD practices - AVOID THIS

The API aims to paraphrase exactly the requested range while avoiding disfluent suggestions. Satisfying both requirements is not always possible; in those cases, the call will result in an empty list of suggestions. Also, avoid paraphrasing texts that start or end mid-word.

For example, consider the sentence “This is a flat out bad example”. Paraphrasing the word “flat” alone in this sentence without violating fluency is not possible, because “flat” is part of the term “flat out”. Paraphrasing “flat” alone is kind of like trying to paraphrase half a word. Cases like this usually yield few or no suggestions.

BEST practices - you should do this

Consider the following example for a paraphrase call:

from ai21 import AI21Client

client = AI21Client(
    # This is the default and can be omitted
    api_key=os.environ.get("AI21_API_KEY"),
)

response = client.paraphrase.create(
  text="My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” We figured that we should create some pages that satisfied this need.",
  start_index=116,
)

And the response:

[
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Therefore, we decided to create some pages that answered this question."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Our team decided to create some pages to answer this question."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” This led to the idea of creating some pages that answered this question."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Thus, some pages were created to provide this information."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Thus, we decided to create some pages that address this issue."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Therefore, we designed some pages that addressed this question."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Therefore, we decided to create some pages that would fulfill this need."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Thus, we created some pages that provide that information."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Thus, we decided to create a few pages about this topic."
   },
   {
      "text":"My team discovered that there was little-to-no information that answered the question, “Is my contractor licensed?” Therefore, we decided to create some pages that would provide this information."
   }
]

You can see that the part until startIndex remains the same in all of the suggestions.

The startIndex can be either the character you wish to paraphrase from, or a whitespace before it (in this case, it would have worked with startIndex=115 as well).

To improve fluency, the range of the paraphrase may contain up to one word per direction. As an example, consider the following sentence (where the range is bolded): I had a good night.

Among the suggestions, you may see “I had a relaxing evening”, where the range is on the limit, as well as “I had an enjoyable evening”, where you can see the range included an extra word before.

Examples

By integrating the Paraphrase API into your system, your users gain an embedded co-writer within the experience. This is useful for virtually all text-based tasks, from marketing content (like that post about a newly specialized API) to emails (a formal report to higher-ups or casual correspondence with a colleague) and even general descriptions. Following are some examples illustrating both use cases and special features you can take advantage of with this API.

General writing platform (generic call)

You can enhance the writing experience of your users by adding paraphrasing functionality to your writing platforms. See the following example for a generic call, without any of the special features. Here is an example for paraphrasing suggestions (note that the API will return up to 10 suggestions in every call):

Text
We will explore the Paraphrase API's advantages and features throughout this page.
Suggestions
The Paraphrase API will be explored throughout this page.
On this page, we will look at the advantages and features of the Paraphrase API.
In this page, we'll explore Paraphrase API's benefits and features.
This page provides an overview of the Paraphrase API's advantages and features
We will discuss the benefits and features of the Paraphrase API throughout this page.

You can use this code and see for yourself:

from ai21 import AI21Client

client = AI21Client(
    # This is the default and can be omitted
    api_key=os.environ.get("AI21_API_KEY"),
)

response = client.paraphrase.create(
  text=="Throughout this page, we will explore the advantages and features of the Paraphrase API.",
)

import requests

fetch("https://api.ai21.com/studio/v1/paraphrase", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "text": "Throughout this page, we will explore the advantages and features of the Paraphrase API."
  }),
  method: "POST"
});

{
   "id":"e218271d-bc3a-3c31-5576-e6b09eb75f8b",
   "suggestions":[
      {
         "text":"We will explore the Paraphrase API's advantages and features throughout this page."
      },
      {
         "text":"The Paraphrase API will be explored throughout this page."
      },
      {
         "text":"On this page, we will look at the advantages and features of the Paraphrase API."
      },
      {
         "text":"In this page, we'll explore Paraphrase API's benefits and features."
      },
      {
         "text":"This page explores the advantages and features of Paraphrase API."
      },
      {
         "text":"This page provides an overview of the Paraphrase API's advantages and features."
      },
      {
         "text":"We will discuss the benefits and features of the Paraphrase API throughout this page."
      },
      {
         "text":"During this page, you will learn about the features and advantages of the Paraphrase API."
      },
      {
         "text":"This page will explore the Paraphrase API's advantages and features."
      },
      {
         "text":"In this page, we'll discuss the advantages and features of the Paraphrase API."
      }
   ]
}

Retail - product descriptions (short style and context use)

Writing product descriptions requires understanding your customers' needs and communicating the features and benefits of your product in an engaging, informative, and compelling manner. Also, as a copywriter, they need to keep a consistent tone in descriptions. On top of that, there is often a strict length restriction, which may cause multiple descriptions for the same product on different platforms. Offering your users different paraphrasing styles, such as shortening, can improve their productivity and help them provide high-quality results, all with their own voice and consistency.

See the following example for a call that combines a short style and the context feature, i.e. - paraphrase only part of the text, while maintaining the full context. Note that unlike in this table, the response will include the full text and not just the paraphrased part.


Text (full context)
This classic cotton t-shirt is made from soft, comfortable cotton and is suitable for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out.
Text to paraphrase
This classic cotton t-shirt is made from soft, comfortable cotton and is suitable for everyday wear.
Suggestions
Designed from 100% soft, comfortable cotton, this classic cotton t-shirt is ideal for everyday use and would make a stylish addition to any wardrobe.

You can use this code and see for yourself:

from ai21 import AI21Client
from ai21.models import ParaphraseStyleType

client = AI21Client(
    # This is the default and can be omitted
    api_key=os.environ.get("AI21_API_KEY"),
)

text = "This classic cotton t-shirt is made from soft, comfortable cotton and is suitable for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
text_to_paraphrase = "This classic cotton t-shirt is made from soft, comfortable cotton and is suitable for everyday wear."

start_index = text.find(text_to_paraphrase)
end_index = start_index + len(text_to_paraphrase)

response = client.paraphrase.create(
  text=text,
  style=ParaphraseStyleType.SHORT,
  start_index=start_index,
  end_index=end_index,
)

{
   "id":"9d0908f7-84f1-5ba4-0c81-14103191e737",
   "suggestions":[
      {
         "text":"Cotton t-shirt made from soft, comfortable cotton for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"Soft, comfortable cotton makes this cotton t-shirt perfect for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"Suitable for everyday wear, this classic cotton t-shirt is made of soft, comfortable cotton. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"The soft, comfortable cotton used in this t-shirt makes it suitable for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"The cotton t-shirt is soft, comfortable, and suitable for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"Soft, comfortable cotton makes for a great everyday t-shirt. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"Comfortable cotton t-shirt for everyday wear made of soft, comfy cotton. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"Soft and comfortable cotton makes this classic cotton t-shirt ideal for daily wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"A classic cotton t-shirt that's comfortable and versatile. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      },
      {
         "text":"The classic cotton t-shirt is soft and comfortable for everyday wear. In addition to providing ultimate comfort and a timeless appearance, this t-shirt has a durable ribbed neckline and a regular fit. It is available in a variety of colors so that you can wear it up or down for any occasion. It's great for running errands or dressing up for a night out."
      }
   ]
}

Customer inquiries (formal style)

It takes years to learn how to sound professional in work emails. You can save your users as much time as possible by providing them with a paraphrased version of their response that sounds professional using the formal tone. Note that unlike in this table, the response will include the full text and not just the paraphrased part.

Text (full context)
Dear (customer name), Thank you for choosing (company name). At (company name), we appreciate our customers and aim to provide good service. Our delivery policy includes: 1- Delivery within 48 hours 2- Delivery within 72 hours for orders above $100. 3- All deliveries are free of charge. 4- All deliveries are insured. 5- All deliveries are tracked. 6- Delivery within 48 hours for orders above $500. (Company name) offers a 10% discount on all purchases. If you require any additional information or assistance, please do not hesitate to contact us. Best regards, John
Text to paraphrase
At (company name), we appreciate our customers and aim to provide good service
Suggestions
We at (company name) are committed to providing excellent service to our customers.