OpenPosterDB

https://openposterdb.com/docs
Admin
OpenPosterDB is an API for generating and serving posters, logos, and backdrops with rating overlays...
Tokens:6,524
Snippets:42
Trust Score:2.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get Backdrop Request Example

Source: https://openposterdb.com/docs

A basic cURL request to retrieve a backdrop image for a specific media item.

```shell
curl 'https://openposterdb.com/{api_key}/imdb/backdrop-default/{id_value}'
```

--------------------------------

### Get Poster Request Example

Source: https://openposterdb.com/docs

A basic cURL command to retrieve a poster image from the OpenPosterDB API.

```shell
curl 'https://openposterdb.com/{api_key}/imdb/poster-default/{id_value}'
```

--------------------------------

### GET /{api_key}/{id_type}/backdrop-default/{id_value}

Source: https://openposterdb.com/docs

Retrieves the default backdrop image for a given movie, TV show, or collection.

```APIDOC
## GET /{api_key}/{id_type}/backdrop-default/{id_value}

### Description
Retrieves the default backdrop image for a given movie, TV show, or collection identified by the provided ID.

### Method
GET

### Endpoint
/{api_key}/{id_type}/backdrop-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - The API key for authentication.
- **id_type** (string) - Required - The type of ID (e.g., movie, tv, collection).
- **id_value** (string) - Required - The value of the ID.

### Response
#### Success Response (200)
Returns the backdrop image.

```

--------------------------------

### GET /{api_key}/isValid

Source: https://openposterdb.com/docs

Validates an API key by sending a GET request to the /{api_key}/isValid endpoint. Returns 200 OK if the key is valid, or 401 if invalid or missing.

```APIDOC
## GET /{api_key}/isValid

### Description
Returns 200 OK if the provided API key is valid. Useful for verifying that an API key is correctly configured.

### Method
GET

### Endpoint
https://openposterdb.com/{api_key}/isValid

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your API key (64-character hex string). Use `t0-free-rpdb` as a free public key if enabled on this instance.

### Request Example
```
curl 'https://openposterdb.com/{api_key}/isValid'
```

### Response
#### Success Response (200)
API key is valid

#### Error Response (401)
Invalid or missing API key.

```

--------------------------------

### GET /{api_key}/{id_type}/backdrop-default/{id_value}

Source: https://openposterdb.com/docs

Returns a JPEG backdrop image with rating badge overlays for the given media item. Uses TMDB as the default source with Fanart.tv as fallback (or vice versa when configured).

```APIDOC
## GET /{api_key}/{id_type}/backdrop-default/{id_value}

### Description
Returns a JPEG backdrop image with rating badge overlays for the given media item. Uses TMDB as the default source with Fanart.tv as fallback (or vice versa when configured).

### Method
GET

### Endpoint
/{api_key}/{id_type}/backdrop-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your API key (64-character hex string). Use `t0-free-rpdb` as a free public key if enabled on this instance.
- **id_type** (string) - Required - The type of media ID being used. Values: `imdb`, `tmdb`, `tvdb`.
- **id_value** (string) - Required - The media ID value. For IMDB use the `tt` prefixed ID (e.g. `tt1234567`). For TMDB prefix with `movie-`, `series-`, or `episode-` (e.g. `movie-550`, `series-1399`, `episode-1396-S1E1`). For TVDB use the numeric ID. Episode IMDb IDs (e.g. `tt0959621`) and TVDB episode IDs are also supported.

#### Query Parameters
- **fallback** (string | null) - Optional - Accepted for RPDB compatibility but has no effect. OpenPosterDB uses TMDB as a fallback source instead of returning a 1x1 pixel placeholder.
- **lang** (string | null) - Optional - Language code for Fanart.tv image selection (e.g. `en`, `de`, `pt-BR`). 2-5 alphanumeric characters or hyphens.
- **imageSize** (string | null) - Optional - Output image size. `small` is only valid for backdrops. Defaults to `medium`. Values: `small`, `medium`, `large`, `very-large`, `verylarge`.
- **ratings_limit** (integer | null) - Optional - Maximum number of rating badges to display (0–10).
- **ratings_order** (string | null) - Optional - Comma-separated rating source keys controlling display order (e.g. `imdb,tmdb,rt`).
- **ratings_exclude** (string | null) - Optional - Comma-separated rating source keys to exclude from display (e.g. `rt,trakt`). Applied before ordering and limiting, so excluded sources free their badge slots for the next preferred source.
- **badge_style** (string | null) - Optional - Badge layout style: `h` (horizontal), `v` (vertical), `d` (default).
- **label_style** (string | null) - Optional - Label rendering style: `t` (text), `i` (icon), `o` (official).
- **badge_size** (string | null) - Optional - Badge size: `xs`, `s`, `m`, `l`, `xl`.
- **badge_direction** (string | null) - Optional - Badge stacking direction (poster only): `d` (default), `h` (horizontal), `v` (vertical).
- **badge_shape** (string | null) - Optional - Badge corner shape: `r` (rounded), `p` (pill).
- **badge_background** (string | null) - Optional - Badge background: `d` (default), `k` (dark), `t` (transparent), `n` (none).
- **position** (string | null) - Optional - Badge anchor position: `bc`, `tc`, `l`, `r`, `tl`, `tr`, `bl`, `br`.
- **image_source** (string | null) - Optional - Image source: `t` (TMDB), `f` (Fanart.tv).
- **textless** (boolean | null) - Optional - Prefer textless images when available.
- **blur** (boolean | null) - Optional - Apply Gaussian blur to the base image (episode only, for spoiler protection).
- **split** (boolean | null) - Optional - Split badges across two opposite sides of the poster (poster only).
- **fit** (string | null) - Optional - Poster fit to the 2:3 frame (poster only): `native`, `cover`, `pad`, `blur`.
- **edge_inset_x** (integer | null) - Optional - Distance (0–50, percent of width) to inset backdrop ratings from the anchored horizontal edge (backdrop only). Ignored for centered positions.
- **edge_inset_y** (integer | null) - Optional - Distance (0–50, percent of height) to inset backdrop ratings from the anchored vertical edge (backdrop only). Ignored for centered positions.

### Request Example
```
curl 'https://openposterdb.com/{api_key}/imdb/backdrop-default/{id_value}'
```

### Response
#### Success Response (200)
Backdrop image (image/jpeg)

#### Response Example
No body

#### Error Responses
- **400** - Invalid request — bad ID type, image size, or language format.
- **401** - Invalid or missing API key.
- **404** - Media item not found.

```

--------------------------------

### GET /{api_key}/{id_type}/logo-default/{id_value}

Source: https://openposterdb.com/docs

Returns a PNG logo image with rating badge overlays for the given media item. Uses TMDB as the default source with Fanart.tv as fallback (or vice versa when configured).

```APIDOC
## GET /{api_key}/{id_type}/logo-default/{id_value}

### Description
Returns a PNG logo image with rating badge overlays for the given media item. Uses TMDB as the default source with Fanart.tv as fallback (or vice versa when configured).

### Method
GET

### Endpoint
/{api_key}/{id_type}/logo-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your API key (64-character hex string). Use `t0-free-rpdb` as a free public key if enabled on this instance.
- **id_type** (string) - Required - The type of media ID being used. Values: `imdb`, `tmdb`, `tvdb`.
- **id_value** (string) - Required - The media ID value. For IMDB use the `tt` prefixed ID (e.g. `tt1234567`). For TMDB prefix with `movie-`, `series-`, or `episode-` (e.g. `movie-550`, `series-1399`, `episode-1396-S1E1`). For TVDB use the numeric ID. Episode IMDb IDs (e.g. `tt0959621`) and TVDB episode IDs are also supported.

#### Query Parameters
- **fallback** (string | null) - Optional - Accepted for RPDB compatibility but has no effect. OpenPosterDB uses TMDB as a fallback source instead of returning a 1x1 pixel placeholder.
- **lang** (string | null) - Optional - Language code for Fanart.tv image selection (e.g. `en`, `de`, `pt-BR`). 2-5 alphanumeric characters or hyphens.
- **imageSize** (string | null) - Optional - Output image size. `small` is only valid for backdrops. Defaults to `medium`. Values: `small`, `medium`, `large`, `very-large`, `verylarge`.
- **ratings_limit** (integer | null) - Optional - Maximum number of rating badges to display (0–10).
- **ratings_order** (string | null) - Optional - Comma-separated rating source keys controlling display order (e.g. `imdb,tmdb,rt`).
- **ratings_exclude** (string | null) - Optional - Comma-separated rating source keys to exclude from display (e.g. `rt,trakt`). Applied before ordering and limiting, so excluded sources free their badge slots for the next preferred source.
- **badge_style** (string | null) - Optional - Badge layout style: `h` (horizontal), `v` (vertical), `d` (default).
- **label_style** (string | null) - Optional - Label rendering style: `t` (text), `i` (icon), `o` (official).
- **badge_size** (string | null) - Optional - Badge size: `xs`, `s`, `m`, `l`, `xl`.
- **badge_direction** (string | null) - Optional - Badge stacking direction (poster only): `d` (default), `h` (horizontal), `v` (vertical).
- **badge_shape** (string | null) - Optional - Badge corner shape: `r` (rounded), `p` (pill).
- **badge_background** (string | null) - Optional - Badge background: `d` (default), `k` (dark), `t` (transparent), `n` (none).
- **position** (string | null) - Optional - Badge anchor position: `bc`, `tc`, `l`, `r`, `tl`, `tr`, `bl`, `br`.
- **image_source** (string | null) - Optional - Image source: `t` (TMDB), `f` (Fanart.tv).
- **textless** (boolean | null) - Optional - Prefer textless images when available.
- **blur** (boolean | null) - Optional - Apply Gaussian blur to the base image (episode only, for spoiler protection).
- **split** (boolean | null) - Optional - Split badges across two opposite sides of the poster (poster only).
- **fit** (string | null) - Optional - Poster fit to the 2:3 frame (poster only): `native`, `cover`, `pad`, `blur`.
- **edge_inset_x** (integer | null) - Optional - Distance (0–50, percent of width) to inset backdrop ratings from the anchored horizontal edge (backdrop only). Ignored for centered positions.
- **edge_inset_y** (integer | null) - Optional - Distance (0–50, percent of height) to inset backdrop ratings from the anchored vertical edge (backdrop only). Ignored for centered positions.

### Request Example
```
curl 'https://openposterdb.com/{api_key}/imdb/logo-default/{id_value}'
```

### Response
#### Success Response (200)
Logo image (image/png)

#### Error Responses
- **400** - Invalid request — bad ID type, image size, or language format.
- **401** - Invalid or missing API key.
- **404** - Media item not found.

#### Response Example
No body (image/png)
```

--------------------------------

### GET /{api_key}/{id_type}/poster-default/{id_value}

Source: https://openposterdb.com/docs

Returns a JPEG poster image with rating badge overlays for the given media item.

```APIDOC
## GET /{api_key}/{id_type}/poster-default/{id_value}

### Description
Returns a JPEG poster image with rating badge overlays for the given media item.

### Method
GET

### Endpoint
/{api_key}/{id_type}/poster-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your API key (64-character hex string). Use `t0-free-rpdb` as a free public key if enabled on this instance.
- **id_type** (string) - Required - The type of media ID being used. Values: `imdb`, `tmdb`, `tvdb`.
- **id_value** (string) - Required - The media ID value. For IMDB use the `tt` prefixed ID (e.g. `tt1234567`). For TMDB prefix with `movie-`, `series-`, or `episode-` (e.g. `movie-550`, `series-1399`, `episode-1396-S1E1`). For TVDB use the numeric ID. Episode IMDb IDs (e.g. `tt0959621`) and TVDB episode IDs are also supported.

#### Query Parameters
- **fallback** (string | null) - Optional - Accepted for RPDB compatibility but has no effect. OpenPosterDB uses TMDB as a fallback source instead of returning a 1x1 pixel placeholder.
- **lang** (string | null) - Optional - Language code for Fanart.tv image selection (e.g. `en`, `de`, `pt-BR`). 2-5 alphanumeric characters or hyphens.
- **imageSize** (string) - Optional - Output image size. `small` is only valid for backdrops. Defaults to `medium`. Values: `small`, `medium`, `large`, `very-large`, `verylarge`.
- **ratings_limit** (integer | null) - Optional - Maximum number of rating badges to display (0–10).
- **ratings_order** (string | null) - Optional - Comma-separated rating source keys controlling display order (e.g. `imdb,tmdb,rt`).
- **ratings_exclude** (string | null) - Optional - Comma-separated rating source keys to exclude from display (e.g. `rt,trakt`). Applied before ordering and limiting, so excluded sources free their badge slots for the next preferred source.
- **badge_style** (string | null) - Optional - Badge layout style: `h` (horizontal), `v` (vertical), `d` (default).
- **label_style** (string | null) - Optional - Label rendering style: `t` (text), `i` (icon), `o` (official).
- **badge_size** (string | null) - Optional - Badge size: `xs`, `s`, `m`, `l`, `xl`.
- **badge_direction** (string | null) - Optional - Badge stacking direction (poster only): `d` (default), `h` (horizontal), `v` (vertical).
- **badge_shape** (string | null) - Optional - Badge corner shape: `r` (rounded), `p` (pill).
- **badge_background** (string | null) - Optional - Badge background: `d` (default), `k` (dark), `t` (transparent), `n` (none).
- **position** (string | null) - Optional - Badge anchor position: `bc`, `tc`, `l`, `r`, `tl`, `tr`, `bl`, `br`.
- **image_source** (string | null) - Optional - Image source: `t` (TMDB), `f` (Fanart.tv).
- **textless** (boolean | null) - Optional - Prefer textless images when available.
- **blur** (boolean | null) - Optional - Apply Gaussian blur to the base image (episode only, for spoiler protection).
- **split** (boolean | null) - Optional - Split badges across two opposite sides of the poster (poster only).
- **fit** (string | null) - Optional - Poster fit to the 2:3 frame (poster only): `native`, `cover`, `pad`, `blur`.
- **edge_inset_x** (integer | null) - Optional - Distance (0–50, percent of width) to inset backdrop ratings from the anchored horizontal edge (backdrop only). Ignored for centered positions.
- **edge_inset_y** (integer | null) - Optional - Distance (0–50, percent of height) to inset backdrop ratings from the anchored vertical edge (backdrop only). Ignored for centered positions.

### Request Example
```
curl 'https://openposterdb.com/{api_key}/imdb/poster-default/{id_value}'
```

### Response
#### Success Response (200)
Poster image (image/jpeg)

#### Response Example
No body

#### Error Responses
- **400** - Invalid request — bad ID type, image size, or language format.
- **401** - Invalid or missing API key.
- **404** - Media item not found.

```

--------------------------------

### Get logo image with curl

Source: https://openposterdb.com/docs

Use this curl command to request a logo image with default settings. Replace {api_key} with your API key (or the free public key 't0-free-rpdb' if enabled) and {id_value} with the media ID (e.g., 'tt1234567' for IMDb). The endpoint returns a PNG image with rating badges; the response is 200 on success, 400 for invalid request, 401 for invalid/missing API key, and 404 if the media item is not found.

```shell
curl 'https://openposterdb.com/{api_key}/imdb/logo-default/{id_value}'

```

--------------------------------

### GET /{api_key}/{id_type}/episode-default/{id_value}

Source: https://openposterdb.com/docs

Retrieves the default episode image for a given TV show episode.

```APIDOC
## GET /{api_key}/{id_type}/episode-default/{id_value}

### Description
Retrieves the default episode image for a given TV show episode identified by the provided ID.

### Method
GET

### Endpoint
/{api_key}/{id_type}/episode-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - The API key for authentication.
- **id_type** (string) - Required - The type of ID (e.g., episode).
- **id_value** (string) - Required - The value of the ID.

### Response
#### Success Response (200)
Returns the episode image.

```

--------------------------------

### GET /{api_key}/{id_type}/episode-default/{id_value}

Source: https://openposterdb.com/docs

Returns a JPEG episode still image with rating badge overlays. Supports optional Gaussian blur for spoiler protection. Falls back to the series poster when no episode still is available.

```APIDOC
## GET /{api_key}/{id_type}/episode-default/{id_value}

### Description
Returns a JPEG episode still image with rating badge overlays. Supports optional Gaussian blur for spoiler protection. Falls back to the series poster when no episode still is available.

### Method
GET

### Endpoint
/{api_key}/{id_type}/episode-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your API key (64-character hex string). Use `t0-free-rpdb` as a free public key if enabled on this instance.
- **id_type** (string) - Required - The type of media ID being used. Values: `imdb`, `tmdb`, `tvdb`.
- **id_value** (string) - Required - The media ID value. For IMDB use the `tt` prefixed ID (e.g. `tt1234567`). For TMDB prefix with `movie-`, `series-`, or `episode-` (e.g. `movie-550`, `series-1399`, `episode-1396-S1E1`). For TVDB use the numeric ID. Episode IMDb IDs (e.g. `tt0959621`) and TVDB episode IDs are also supported.

#### Query Parameters
- **fallback** (string | null) - Optional - Accepted for RPDB compatibility but has no effect. OpenPosterDB uses TMDB as a fallback source instead of returning a 1x1 pixel placeholder.
- **lang** (string | null) - Optional - Language code for Fanart.tv image selection (e.g. `en`, `de`, `pt-BR`). 2-5 alphanumeric characters or hyphens.
- **imageSize** (string) - Optional - Output image size. `small` is only valid for backdrops. Defaults to `medium`. Values: `small`, `medium`, `large`, `very-large`, `verylarge`.
- **ratings_limit** (integer | null) - Optional - Maximum number of rating badges to display (0–10).
- **ratings_order** (string | null) - Optional - Comma-separated rating source keys controlling display order (e.g. `imdb,tmdb,rt`).
- **ratings_exclude** (string | null) - Optional - Comma-separated rating source keys to exclude from display (e.g. `rt,trakt`). Applied before ordering and limiting, so excluded sources free their badge slots for the next preferred source.
- **badge_style** (string | null) - Optional - Badge layout style: `h` (horizontal), `v` (vertical), `d` (default).
- **label_style** (string | null) - Optional - Label rendering style: `t` (text), `i` (icon), `o` (official).
- **badge_size** (string | null) - Optional - Badge size: `xs`, `s`, `m`, `l`, `xl`.
- **badge_direction** (string | null) - Optional - Badge stacking direction (poster only): `d` (default), `h` (horizontal), `v` (vertical).
- **badge_shape** (string | null) - Optional - Badge corner shape: `r` (rounded), `p` (pill).
- **badge_background** (string | null) - Optional - Badge background: `d` (default), `k` (dark), `t` (transparent), `n` (none).
- **position** (string | null) - Optional - Badge anchor position: `bc`, `tc`, `l`, `r`, `tl`, `tr`, `bl`, `br`.
- **image_source** (string | null) - Optional - Image source: `t` (TMDB), `f` (Fanart.tv).
- **textless** (boolean | null) - Optional - Prefer textless images when available.
- **blur** (boolean | null) - Optional - Apply Gaussian blur to the base image (episode only, for spoiler protection).
- **split** (boolean | null) - Optional - Split badges across two opposite sides of the poster (poster only).
- **fit** (string | null) - Optional - Poster fit to the 2:3 frame (poster only): `native`, `cover`, `pad`, `blur`.
- **edge_inset_x** (integer | null) - Optional - Distance (0–50, percent of width) to inset backdrop ratings from the anchored horizontal edge (backdrop only). Ignored for centered positions.
- **edge_inset_y** (integer | null) - Optional - Distance (0–50, percent of height) to inset backdrop ratings from the anchored vertical edge (backdrop only). Ignored for centered positions.

### Request Example
```
curl 'https://openposterdb.com/{api_key}/imdb/episode-default/{id_value}'
```

### Response
#### Success Response (200)
Episode image (image/jpeg)

#### Error Responses
- **400** - Invalid request — bad ID type, image size, or language format, or non-episode ID used on episode endpoint.
- **401** - Invalid or missing API key.
- **404** - Episode not found.

```

--------------------------------

### Get Episode Image Request

Source: https://openposterdb.com/docs

A cURL command to retrieve an episode still image using the required API key, ID type, and media ID value.

```shell
curl 'https://openposterdb.com/{api_key}/imdb/episode-default/{id_value}'
```

--------------------------------

### GET /{api_key}/{id_type}/logo-default/{id_value}

Source: https://openposterdb.com/docs

Retrieves the default logo image for a given movie, TV show, or collection.

```APIDOC
## GET /{api_key}/{id_type}/logo-default/{id_value}

### Description
Retrieves the default logo image for a given movie, TV show, or collection identified by the provided ID.

### Method
GET

### Endpoint
/{api_key}/{id_type}/logo-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - The API key for authentication.
- **id_type** (string) - Required - The type of ID (e.g., movie, tv, collection).
- **id_value** (string) - Required - The value of the ID.

### Response
#### Success Response (200)
Returns the logo image.

```

--------------------------------

### GET /{api_key}/{id_type}/poster-default/{id_value}

Source: https://openposterdb.com/docs

Retrieves the default poster image for a given movie, TV show, or collection.

```APIDOC
## GET /{api_key}/{id_type}/poster-default/{id_value}

### Description
Retrieves the default poster image for a given movie, TV show, or collection identified by the provided ID.

### Method
GET

### Endpoint
/{api_key}/{id_type}/poster-default/{id_value}

### Parameters
#### Path Parameters
- **api_key** (string) - Required - The API key for authentication.
- **id_type** (string) - Required - The type of ID (e.g., movie, tv, collection).
- **id_value** (string) - Required - The value of the ID.

### Response
#### Success Response (200)
Returns the poster image.

```

--------------------------------

### Validate API key with cURL

Source: https://openposterdb.com/docs

Use this cURL command to verify if an API key is valid. Replace {api_key} with your 64-character hex string or the public key t0-free-rpdb.

```shell
curl 'https://openposterdb.com/{api_key}/isValid'
```
Tokens:
Raw