---
title: "Generate a placard from an image"
method: GET
path: "/{api_key}/placard.png"
tags: ["Placards"]
---

# Generate a placard from an image

`GET /{api_key}/placard.png`

## Request

- Base URL: `https://api.top-posters.com`
- URL: `https://api.top-posters.com/{api_key}/placard.png`
- Auth: none declared
- TypeScript: <https://skmtc.dev/top-posters/apis/top-posters-api/docs/:api_key/placard.png/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `api_key` string, required: API Key, in the form `TP-XXXXX...`

## Query parameters

- `image` string, required: Public URL of a PNG, JPEG, WebP, GIF or SVG image, up to 2 MB.
- `header` string, 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.
- `title` string, 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.
- `subtitle` string: 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.
- `style` string, 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`.
- `background` string: 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.
- `shuffle` boolean: 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).
- `provider` string: Provider identity for its predefined background, e.g. shudder, letterboxd or myanimelist. background takes precedence.
- `show_brand` boolean, nullable: Use `header`: false is an empty header.
- `layout` 'default' | 'list', nullable: Use `align`: `list` is `align=center`.

## Response `200`

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

## Other responses

- `400`: Invalid header, title, subtitle, style, design or background
- `404`: Placards are turned off in the key owner's dashboard
- `422`: The image URL is not public, not an image, too large or unreachable

## Changes

- **2026-11-13** `58f53e02c8af`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/top-posters/apis/top-posters-api/changes/:api_key/placard.png/get.md)

---

[API](https://skmtc.dev/top-posters/apis/top-posters-api.md) - [All operations](https://skmtc.dev/top-posters/apis/top-posters-api/llms.txt) - [OpenAPI document](https://skmtc.dev/top-posters/apis/top-posters-api/revisions/58f53e02c8af?raw)