POST /v1/pinglish

Generate Finglish/Pinglish that stays aligned to Persian.

Choose a reader-friendly or systematic transliteration and receive word-level alignment back to the exact Persian source. The endpoint is pronunciation support, not a replacement for Persian script.

POSThttps://api.vowelmarks.com/v1/pinglish

Updated September 15, 2026 · API version 1

Request options

style: readable (default) favors familiar, approachable Finglish/Pinglish spellings.
style: systematic favors a more consistent transliteration convention.
vowel_notation: double_a (default) writes long ā as aa.
vowel_notation: macron writes long ā with a macron where applicable.

Field	Type	Default	Description
`text`	string	Required	Persian or mixed-script text with at least one Persian-script letter; maximum 6,000 Unicode code points. The complete serialized JSON body must be at most 32 KiB (32,768 bytes).
`style`	enum	`readable`	`readable` or `systematic`.
`vowel_notation`	enum	`double_a`	`double_a` or `macron`.

{
  "text": "من فارسی می‌خوانم",
  "style": "readable",
  "vowel_notation": "double_a"
}

Response and alignment

Each alignment item uses a half-open source interval: source_start is included and source_end is excluded. Both are Unicode code-point positions. Source punctuation or spacing may sit between aligned words rather than becoming its own word item.

{
  "original": "من فارسی می‌خوانم",
  "pinglish": "man faarsi mikhaanam",
  "style": "readable",
  "vowel_notation": "double_a",
  "alignment": [
    { "source_start": 0, "source_end": 2, "source": "من", "pinglish": "man" }
  ],
  "warnings": [],
  "request_id": "95b…",
  "engine_version": "vowelmarks-api-v1.2026-08-10",
  "usage": {
    "meter": "text", "input_code_points": 17,
    "multiplier": 1, "units": 17,
    "additional_units": 0, "cache_hit": false
  }
}

Mixed-script input

The request must contain a Persian-script letter, but it may also include Latin text, URLs, numbers, punctuation, and ZWNJ. warnings can identify mixed-script conditions that deserve review in a client interface. Preserve original as the source of truth.

Use alignment to highlight the corresponding Persian word.
Show Finglish/Pinglish as optional pronunciation help beside Persian script.
Do not assume one transliterated token per whitespace-delimited token.
Successful cache hits are charged normally because they deliver the same product result.