Sawalni API
APIsDocumentationOpen portal ↗
Omneity Labs API collection ↗Integration quickstart →API keys and playgrounds →
API Reference

Ziryab Rhymes & Lyrics API

Ziryab is a rhyme and lyrics model built on Sawtone for rhyme scoring, vocabulary search, replacement suggestions, and lyric structure analysis. Vocabulary-backed routes use Sawtone's supported multilingual language indexes, and stale or undersized cached rhyme indexes are rebuilt automatically when larger requested build settings require it.

Endpoints

CapabilityEndpoint
Rhyme scoringPOST /v1/language/rhyme/score
Rhyme searchPOST /v1/language/rhyme/search
Lyric replacement suggestionsPOST /v1/language/lyrics/suggest-replacements
Lyric structure scoringPOST /v1/language/lyrics/score

Rhyme Score

Score explicit word pairs and optionally include IPA forms or phonetic similarity components.

Example — JavaScript

javascript
const response = await fetch("https://api.sawalni.com/v1/language/rhyme/score", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pairs: [["night", "light"], ["time", "song"]],
    language: "eng_Latn",
    include_ipa: true,
    include_components: true,
  }),
})

const data = await response.json()
console.log(data.results)

Example — Python

python
import requests

response = requests.post(
    "https://api.sawalni.com/v1/language/rhyme/score",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "pairs": [["night", "light"], ["time", "song"]],
        "language": "eng_Latn",
        "include_ipa": True,
        "include_components": True,
    },
    timeout=30,
)

data = response.json()
print(data["results"])

Response

json
{
  "language": "eng_Latn",
  "results": [
    {
      "a": "night",
      "b": "light",
      "rhyme_score": 0.97,
      "phonetic_cosine": 0.95,
      "ipa_a": "naɪt",
      "ipa_b": "laɪt"
    },
    {
      "a": "time",
      "b": "song",
      "rhyme_score": 0.18,
      "phonetic_cosine": 0.11,
      "ipa_a": "taɪm",
      "ipa_b": "sɔŋ"
    }
  ],
  "usage": {
    "input_bytes": 112,
    "input_count": 2,
    "processing_ms": 7.6
  }
}

Rhyme Search

Search a supported vocabulary index for rhyme candidates.

Example — JavaScript

javascript
const response = await fetch("https://api.sawalni.com/v1/language/rhyme/search", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "rain",
    language: "eng_Latn",
    vocabulary: "common-lyrics",
    top_k: 5,
    include_ipa: true,
  }),
})

const data = await response.json()
console.log(data.results)

Example — Python

python
import requests

response = requests.post(
    "https://api.sawalni.com/v1/language/rhyme/search",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "query": "rain",
        "language": "eng_Latn",
        "vocabulary": "common-lyrics",
        "top_k": 5,
        "include_ipa": True,
    },
    timeout=30,
)

data = response.json()
print(data["results"])

Response

json
{
  "language": "eng_Latn",
  "query": "rain",
  "results": [
    {
      "word": "train",
      "rhyme_score": 0.96,
      "syllables": 1,
      "ipa": "tɹeɪn"
    },
    {
      "word": "lane",
      "rhyme_score": 0.84,
      "syllables": 1,
      "ipa": "leɪn"
    },
    {
      "word": "again",
      "rhyme_score": 0.8,
      "syllables": 2,
      "ipa": "əˈɡɛn"
    }
  ],
  "usage": {
    "input_bytes": 97,
    "input_count": 1,
    "processing_ms": 10.4
  }
}

Lyric Replacement Suggestions

Suggest replacements for the last word in a line, or pass target explicitly. When enough strong candidates exist, replacement filtering now prefers candidates with high rhyme-tail compatibility, and include_components can expose separate rhyme component scores alongside IPA forms.

Example — JavaScript

javascript
const response = await fetch("https://api.sawalni.com/v1/language/lyrics/suggest-replacements", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    line: "I keep my heart above the rain",
    target: "rain",
    language: "eng_Latn",
    vocabulary: "common-lyrics",
    top_k: 5,
    include_components: true,
  }),
})

const data = await response.json()
console.log(data)

Example — Python

python
import requests

response = requests.post(
    "https://api.sawalni.com/v1/language/lyrics/suggest-replacements",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "line": "I keep my heart above the rain",
        "target": "rain",
        "language": "eng_Latn",
        "vocabulary": "common-lyrics",
        "top_k": 5,
        "include_components": True,
    },
    timeout=30,
)

data = response.json()
print(data)

Response

json
{
  "line": "I keep my heart above the rain",
  "target": "rain",
  "suggestions": [
    {
      "word": "lane",
      "rhyme_score": 0.93,
      "rhymenet_score": 0.95,
      "rhyme_tail_score": 0.98,
      "ipa": "leɪn",
      "target_ipa": "ɹeɪn"
    },
    {
      "word": "train",
      "rhyme_score": 0.9,
      "rhymenet_score": 0.92,
      "rhyme_tail_score": 0.97,
      "ipa": "tɹeɪn",
      "target_ipa": "ɹeɪn"
    }
  ],
  "usage": {
    "input_bytes": 128,
    "input_count": 1,
    "processing_ms": 14.8
  }
}

Lyric Score

Evaluate stanza rhyme structure.

Example — JavaScript

javascript
const response = await fetch("https://api.sawalni.com/v1/language/lyrics/score", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "I walk alone beneath the night
I chase the moon and lose the light",
    language: "eng_Latn",
    rhyme_threshold: 0.64,
    include_internal_rhymes: true,
  }),
})

const data = await response.json()
console.log(data)

Example — Python

python
import requests

response = requests.post(
    "https://api.sawalni.com/v1/language/lyrics/score",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "text": "I walk alone beneath the night
I chase the moon and lose the light",
        "language": "eng_Latn",
        "rhyme_threshold": 0.64,
        "include_internal_rhymes": True,
    },
    timeout=30,
)

data = response.json()
print(data)

Response

json
{
  "summary": {
    "overall_score": 0.86,
    "detected_scheme": "AA"
  },
  "lines": [
    {
      "text": "I walk alone beneath the night",
      "end_word": "night"
    },
    {
      "text": "I chase the moon and lose the light",
      "end_word": "light"
    }
  ],
  "usage": {
    "input_bytes": 143,
    "input_count": 2,
    "processing_ms": 16.2
  }
}

Supported Vocabulary Tiers

TierDescription
rawFull Wikilangs vocabulary for the language
commonHigher-frequency vocabulary subset
common-lyricsVocabulary subset tuned for lyric and rhyme workflows

Notes

  • Vocabulary-backed routes require a supported language index such as eng_Latn, fra_Latn, arb_Arab, or ary_Arab.
  • Use common-lyrics when you want rhyme search and lyric suggestions tuned for songwriting workflows.
  • Requests are metered on input bytes.