Skip to content

url_construction.rst

Latest commit

 

History

History
154 lines (124 loc) · 5.31 KB

url_construction.rst

File metadata and controls

154 lines (124 loc) · 5.31 KB
Raw

Constructing memegen URLs

When memeplotlib renders a memegen-catalogue meme it does so by asking the upstream API to compose the image — same path-and-query grammar documented for api.memegen.link. This page is the memeplotlib-flavoured version of the unified guide proposed in jacebrowning/memegen#993.

You normally don't need to write a URL by hand — :func:`memeplotlib.meme` forwards every relevant knob — but the builder is a public API (:func:`memeplotlib.build_memegen_url`) for agents and scripts that need deterministic URLs.

URL shape

{api_base}/images/{template_id}/{line_1}/{line_2}/.../{line_n}.{ext}?{query}

Each line_i is encoded so it survives a URL path. Empty slots are encoded as _ to preserve slot ordering. Up to Template.lines_count slots are accepted; trailing empty slots may be omitted but middle empty slots must remain.

Escape table

Memegen uses a tilde-escape scheme for characters that are illegal or ambiguous in a URL path. memeplotlib ships :func:`memeplotlib._text.encode_text_for_url` which applies it.

Character Encoding
space _
_ __
- --
" ''
? ~q
& ~a
% ~p
# ~h
/ ~s
\ ~b
< ~l
> ~g
newline ~n

Empty caption slots become a single _ rather than the empty string. Emoji and HTML aliases (:thumbsup:, :fire:) are passed through verbatim — memegen resolves them server-side.

Query parameters

Every parameter below is optional. memeplotlib only emits a query string when at least one parameter is supplied.

style= Template-specific style name (e.g. maga for ds) or an arbitrary image URL for an ad-hoc overlay. May appear multiple times when overlays are stacked.
font= Memegen font alias. The closed set (:data:`memeplotlib._url.MEMEGEN_FONT_ALIASES`) is impact, thick, thin, tiny, comic, notosans, kalam, he, jp, tw, default. Fonts outside that set fall through to the Pillow backend automatically under backend="auto".
color= "fg" or "fg,bg". HTML names or hex codes.
width= Output width in pixels.
height= Output height in pixels.
layout= Alternate layout (e.g. top).
background= Custom background URL. Composes with style=<url> overlays.
center= "x,y" overlay anchor ([0, 1] floats). Paired with an style= overlay.
scale= Overlay scale factor. Paired with an style= overlay.

Output formats

The path extension selects the format:

  • .png — default; lossless transparency.
  • .jpg / .jpeg — smaller, lossy.
  • .gif — animated when the template's blank is animated; static background + animated text otherwise.
  • .webp — modern lossy/lossless hybrid.

Set with meme(..., extension="jpg") or config["extension"] = "jpg".

Worked examples

A plain caption pair:

from memeplotlib import build_memegen_url

build_memegen_url(
    "buzz",
    ["memes", "memes everywhere"],
    api_base="https://api.memegen.link",
)
# → https://api.memegen.link/images/buzz/memes/memes_everywhere.png

A template style plus dimensions plus a two-colour caption:

build_memegen_url(
    "ds",
    ["the dress is black and blue.", "the dress is gold and white."],
    api_base="https://api.memegen.link",
    template_style="maga",
    font="comic",
    color="white,black",
    width=600,
    extension="jpg",
)
# → /images/ds/the_dress_is_black_and_blue./the_dress_is_gold_and_white..jpg
#   ?style=maga&font=comic&color=white,black&width=600

A custom-background ad-hoc overlay:

build_memegen_url(
    "fine",
    ["this is fine"],
    api_base="https://api.memegen.link",
    background="https://example.com/bg.png",
    overlays=[{"style": "https://example.com/dog.png",
               "center": (0.5, 0.7), "scale": 0.4}],
)

Notes for automated clients

  • Bootstrap with GET /templates/ once and cache. Per-template metadata (Template.from_memegen) hits GET /templates/<id>.
  • Template.example is the canonical "guaranteed-valid URL" smoke test — useful for asserting that a template id is live without composing a caption yourself.
  • Memegen normalises raw POSTed text to the escape forms above and returns the canonical URL. memeplotlib performs the same encoding locally via :func:`encode_text_for_url`.
  • Behaviour when lines exceeds Template.lines_count: extra path segments are ignored by memegen. memeplotlib does not pre-truncate; pass exactly the slots you intend.