TOtop-posters
Placards

Generate a placard from an image

Changed on

Generate a placard that presents an app, a service, a plan or a list, as a 2:3 poster or a 16:9 banner.

header at the top, title and subtitle at the bottom and the image centred in the space between them, or filling the whole placard with style=cover; align puts the texts on the left or in the centre, design chooses how they are drawn. The look follows the key owner's Placards settings in the dashboard, where placards can also be turned off (404) and each of header, title and subtitle hidden; design, align and style in the URL override the settings. Each request counts towards the monthly allowance like any other image.

get/{api_key}/placard.png

Request

Path parameters

api_keystring required

API Key, in the form TP-XXXXX...

Query parameters

imagestring required

Public URL of a PNG, JPEG, WebP, GIF or SVG image, up to 2 MB.

headerstring nullable

Small text in capitals at the top, e.g. TOP POSTERS or the app name. Empty or omitted: no header. Up to 40 characters; a long one wraps onto a second line.

titlestring required

Bottom title, e.g. the app or the list name. Up to 256 characters: it shrinks to stay on one line, then wraps onto several.

subtitlestring

Small text in capitals: under the title with design=classic, above it as a label (e.g. a person's role) with design=minimal. Up to 40 characters; a long one shrinks, then wraps.

align'left' | 'center' nullable

Alignment of the three texts: left or center. When omitted, the dashboard choice (center by default).

kind'person' | 'logo' nullable

What the image shows: person (a photo of someone) or logo (a wordmark or an icon, the default). Without style, the dashboard choice for that kind decides where the image goes: cover, tile, plain for people, plain, tile, badge for logos.

stylestring nullable

Where the image goes (plain, tile, badge, cover). plain, tile and badge centre it as a logo; cover fills the poster with it (made for photos, e.g. a person), and on a banner keeps it whole on the left over a blurred copy of itself. When omitted, the dashboard choice for kind.

backgroundstring

Gradient as one hex colour (1d2a48, darkened towards the bottom) or two joined by a dash (1d2a48-0e1424). Overrides the provider palette; otherwise the logo colour is used.

format'poster' | 'banner'

poster: 400×600 (2:3). banner: 1280×720 (16:9), the same layout for landscape rows.

shuffleboolean

The placard presents a rotating list: a small shuffle marker goes in the top-right corner, unless it is turned off in the dashboard.

design'classic' | 'minimal' nullable

How text and marker are drawn. classic: plain text on the image. minimal: title and subtitle in a light Minimal box, and the shuffle marker on a raised disc. When omitted, the dashboard choice (minimal by default).

providerstring

Provider identity for its predefined background, e.g. shudder, letterboxd or myanimelist. background takes precedence.

show_brandboolean nullable

Use header: false is an empty header.

layout'default' | 'list' nullable

Use align: list is align=center.

Response

Placard generated (PNG with transparent corners): 400×600 or, with format=banner, 1280×720

Changes