Render a Mermaid diagram with an API

This guide describes production API usage. The website demo has a separate, smaller anonymous allowance. Subscribe to an available listing before running the scripts.

Choose your marketplace

The complete scripts below target RapidAPI. Use the provider tabs for the matching base URL and authentication pattern; ApyHub capabilities may be split across listings and remain unavailable until published. Never use a pending listing as a production endpoint.

import os
import httpx

base_url = "https://diagram-math-code-render-api.p.rapidapi.com"
headers = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "diagram-math-code-render-api.p.rapidapi.com",
}
payload = {
    "engine": "mermaid",
    "source": "flowchart LR\n  A[Your idea] --> B[An API call]\n  B --> C[A finished diagram]",
    "format": "png",
    "width": 900,
    "scale": 1,
    "theme": "neutral",
}
response = httpx.post(
    base_url + "/v1/render/diagram",
    headers=headers, json=payload, timeout=120
)
response.raise_for_status()
with open("result.png", "wb") as output:
    output.write(response.content)

Before you start

Subscribe on RapidAPI and keep RAPIDAPI_KEY on your server. Python examples require Python 3.10+ and requests (python -m pip install requests).

Create an SVG flowchart in under five minutes. In RapidAPI, subscribe to BASIC and copy your key from the endpoint console. Keep it in an environment variable:

export RAPIDAPI_KEY='your-key'
export RAPIDAPI_HOST='diagram-math-code-render-api.p.rapidapi.com'

Send Mermaid source as JSON and save the returned SVG:

curl --fail-with-body --max-time 45 --request POST \
  --url "https://${RAPIDAPI_HOST}/v1/render/diagram" \
  --header "content-type: application/json" \
  --header "x-rapidapi-host: ${RAPIDAPI_HOST}" \
  --header "x-rapidapi-key: ${RAPIDAPI_KEY}" \
  --data '{
    "engine": "mermaid",
    "source": "flowchart LR\n  A[Idea] --\u003e B{Ready?}\n  B --\u003e|Yes| C[Ship]\n  B --\u003e|No| A",
    "format": "svg",
    "theme": "neutral"
  }' \
  --output diagram.svg

The \u003e sequences are standard JSON Unicode escapes for the arrow character; the API receives ordinary Mermaid arrows after JSON decoding.

Open diagram.svg in a browser or reference it from Markdown. To get a PNG data URI that can be assigned directly to an HTML image element, omit format:

import os
import requests

host = "diagram-math-code-render-api.p.rapidapi.com"
response = requests.post(
    f"https://{host}/v1/render/diagram",
    headers={
        "Content-Type": "application/json",
        "X-RapidAPI-Host": host,
        "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    },
    json={
        "engine": "mermaid",
        "source": "sequenceDiagram\n  User-\u003e\u003eAPI: Render\n  API--\u003e\u003eUser: Image",
    },
    timeout=45,
)
response.raise_for_status()
result = response.json()
print(result["width"], result["height"], result["cached"])
# Assign result["data_uri"] to the src property of an HTML image element.

Use graphviz, d2 or vegalite in the same endpoint. Invalid syntax returns a 422 JSON error with an engine and source line where available; fix the source instead of retrying it unchanged.

Errors, limits and allowance

Check HTTP status before using the output. Correct 422 source/schema errors instead of retrying them. For temporary 429/502/503/504 responses, use bounded retries and honor Retry-After; monthly quota exhaustion needs renewed allowance or a plan change. Every call and retry may consume allowance, including identical inputs. Caching does not make requests free. Keep sequential jobs within your current plan’s rate. PDF requires a paid plan; BASIC supports the other formats. Source is limited to 64 KiB and code to 2,000 lines. A 45-second client timeout gives transport headroom and is not a latency guarantee. See the Developer guide’s format limits and Privacy Notice.