Rewrite API [beta]

The Rewrite API of AI21 Studio provides you access to our state-of-the-art paraphrasing engine. It was designed specifically for paraphrasing purposes and has been fine-tuned for that task. Consequently, it's easier to integrate into your systems, and since it's optimized for this objective - it's also more efficient (and therefore cheaper) than building it from scratch.

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: adjust the tone and rewrite only parts of a text (while keeping the whole context).

By specifying an (optional) intent, you can generate paraphrases that are longer, shorter, more formal or more casual than the original text. You can rewrite a specific span while keeping the surrounding text unchanged by passing spanStart and spanEnd (also optional).

import requests

requests.post(
    "https://api.ai21.com/studio/v1/experimental/rewrite",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "text": "You can now use AI21 Studio to rewrite text.",
        "intent": "general"
    }
)

fetch("https://api.ai21.com/studio/v1/experimental/rewrite", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "text": "You can now use AI21 Studio to rewrite text.",
    "intent": "general"
  }),
  method: "POST"
});

curl https://api.ai21.com/studio/v1/experimental/rewrite \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -X POST \
    --data-raw '{
        "text": "You can now use AI21 Studio to rewrite text.",
        "intent": "general"
    }' 

{
  "suggestions": [
    {"text": "AI21 Studio now allows you to rewrite text."},
    {"text": "You can now rewrite text using AI21 Studio."},
    {"text": "AI21 Studio can now be used to rewrite text."},
    {"text": "AI21 Studio now lets you rewrite text."},
    {"text": "Rewriting text is now possible in AI21 Studio."},
    {"text": "It is now possible to rewrite text in AI21 Studio."},
    {"text": "Using AI21 Studio, you are now able to rewrite text."},
    {"text": "Rewrite text with AI21 Studio now."},
    {"text": "In AI21 Studio, you can rewrite text."},
    {"text": "AI21 Studio now provides rewriting functionality."}
  ]
}

Notes about Paraphrasing Spans

Spans are expected to align with full words. Paraphrasing spans that start or end in the middle of a word will result in unexpected behavior (usually - no suggestions returned).

Spans - what NOT to do

The Rewrite API aims to rewrite exactly the requested span while avoiding disfluent suggestions. Satisfying both requirements is not always possible.

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 return few or no suggestions.

Spans - how to do it right

Consider the following example:

You can see that the part until spanStart remains the same.

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