> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/fanart-tv.md).

# Fanart.tv

Add optional Fanart.tv artwork alongside TMDb metadata.

Fanart.tv supplies optional movie and show logos and backgrounds, plus movie disc artwork for CrossWatch. It supplements [TMDb Metadata](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/tmdb-metadata.md); it does not replace title matching or sync watchlists, ratings or watched history.

### Enable Fanart.tv

1. Configure a **TMDb Metadata** API key first. A key entered only under **TMDb (Sync)** does not enable metadata artwork.
2. Open **Settings → Connections → Metadata → Fanart.tv**.
3. In **API key**, leave the optional key fields empty to use the included CrossWatch project key, then select **Connect fanart.tv**. No Fanart.tv account is required. The status changes to **Connected** after a successful check.
4. In **Settings**, choose sources separately for **Logos** and **Backgrounds**. Both default to **fanart.tv first**.
5. Select **Save changes**, then reload open pages to see the change.

Connecting Fanart.tv lets CrossWatch contact Fanart.tv when artwork is needed.

### Choose an artwork source

| Choice              | Behavior                                                                                |
| ------------------- | --------------------------------------------------------------------------------------- |
| **fanart.tv first** | Prefer Fanart.tv; use TMDb when suitable Fanart.tv artwork is unavailable.              |
| **TMDb first**      | Use Fanart.tv only when TMDb has no image. This is especially useful for missing logos. |
| **TMDb only**       | Use TMDb for this artwork type. The other artwork type keeps its own setting.           |

Logos and backgrounds can appear in media details, Now Playing, Hub, dashboard widgets and Tracker. Automatic posters and episode stills use TMDb. Administrators can [choose artwork per title](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/artwork-selection.md), including Fanart.tv posters and movie discs. Automatic background selection favors images without text; automatic logos use available artwork.

Artwork availability varies by title. TV artwork also needs a matching TVDB ID, which CrossWatch looks up through TMDb. Missing artwork or an unavailable Fanart.tv service falls back to TMDb when possible.

### Optional keys

For earlier access to newly approved artwork, get a [personal API key from Fanart.tv](https://fanart.tv/get-an-api-key/), paste it into **Personal API key (optional)** in the **API key** tab and select **Save changes**. Leave **Own project API key (optional)** empty to use the CrossWatch project key.

Fanart.tv makes new uploads available after seven days with a project key, after two days with a personal key, or immediately for VIP members using their personal key. CrossWatch also caches artwork, so newly available images may not appear immediately.

If you already have your own project key, you can enter it in **Own project API key (optional)**. Saving changed keys checks them before enabling the connection. Use **Reconnect** if you need to check the connection again.

### Turn it off or remove keys

Use **Delete connection** to turn Fanart.tv off and remove both saved keys from CrossWatch. To keep the connection but use automatic TMDb logos and backgrounds, set both sources to **TMDb only** and select **Save changes**. Saved per-title artwork choices remain until you reset them with **Use automatic**. Reload open pages afterward.

### Troubleshooting

| Problem                         | What to check                                                                                                                              |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Fanart.tv cannot connect        | Configure the key under **TMDb Metadata**, then reopen Fanart.tv.                                                                          |
| Artwork still looks the same    | Reload the page and check the source choice. TMDb first keeps existing TMDb images; Fanart.tv may not have an alternative.                 |
| A show has no Fanart.tv artwork | Check that the title is matched correctly and has a TVDB match in TMDb. TMDb artwork is used when available.                               |
| A key is rejected               | Check that a personal key and a project key are in their respective fields. You can leave the project field empty to use the built-in key. |
| Network error or rate limit     | Check network access from the CrossWatch host and retry later.                                                                             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/fanart-tv.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
