> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wardrobe

> Dress any character in a chosen outfit from your code or AI agent. Write the outfit's @handle next to the character in an image or video prompt and they wear exactly those clothes. Free library included.

An outfit is a clean picture of clothes with nobody in them, and a handle. Write its `@handle`
next to a [character](https://docs.budgetpixel.com/characters.md) in a prompt and the character wears exactly those clothes, in
place of their own: the outfit's picture goes with the mention as a reference image, and its
description is added to the prompt. The same outfit stays the same from one image to the next
and in video.

```bash theme={null}
curl https://api.budgetpixel.com/v1/images/nano-banana-2.1 \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "@barry wearing @camel_belted_overcoat_outfit, walking down a rainy street, full-body photo"}'
```

You can use your own outfits, the ones you saved, and the **free library**: everyday clothes,
workwear, formal and party outfits, sportswear, swimwear, sleepwear, costumes, traditional
dress and seasonal outfits, free for every user and growing over time.

> [card] [The free wardrobe library](https://budgetpixel.com/wardrobe)
>
> Browse every outfit, see its handle, and make your own from a photo or a description.

> [!NOTE]
>
> Available on **every paid plan**, like the rest of the API. Over [MCP](https://docs.budgetpixel.com/mcp-server.md), your
> agent finds outfits with `search_wardrobe` and `get_wardrobe_item`, adds new ones with
> `add_wardrobe_item`, and dresses a character with the same @mention in `generate_image` or
> `generate_video`.

## Wearing an outfit

* Write the character, then the outfit: `"@rosa wearing @silver_sequin_mini_dress_set at a
  rooftop party"`. With two people, name an outfit for each: `"@barry in
  @camel_belted_overcoat_outfit and @rosa in @red_embroidered_qipao_set, walking together"`.
* An outfit works on every model a character works on (see `supported_models` on
  [`GET /v1/characters/{handle}`](https://docs.budgetpixel.com/api-reference/characters/get-a-character)).
* Up to **4 outfits** per generation, beside up to 4 characters. Their pictures count as
  reference images, in the model's limit and in the price.
* An outfit on its own, with no character, sends its picture as a reference: useful for a
  product shot or to restyle it.
* When a character and an outfit share a handle, the character wins.

## List the outfits you can use

```bash theme={null}
curl "https://api.budgetpixel.com/v1/wardrobe?q=coat&category=outerwear" \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```

```json theme={null}
{
  "items": [
    {
      "handle": "camel_belted_overcoat_outfit",
      "mention": "@camel_belted_overcoat_outfit",
      "name": "Camel Belted Overcoat Outfit",
      "kind": "outfit",
      "category": "outerwear",
      "fit": "unisex",
      "colors": ["camel", "black"],
      "tags": ["smart casual", "winter", "minimalist"],
      "description": "Camel mid-length wool blend overcoat with waist belt, black turtleneck, black tailored trousers, black leather dress shoes.",
      "source": "house",
      "preview_url": "https://…",
      "thumbnail_url": "https://…"
    }
  ],
  "count": 1,
  "how_to_use": "Write @handle in the prompt of any image or video generation …"
}
```

[`GET /v1/wardrobe`](https://docs.budgetpixel.com/api-reference/wardrobe/list-outfits-you-can-use) returns your own outfits
first, then the ones you saved, then the free library. Filter with `source` (`mine`, `saved`,
`house`), `q` (words that must all appear in the name, handle, description, colours or tags),
`category` (`everyday`, `work`, `formal`, `party`, `sport`, `swim`, `outerwear`, `sleepwear`,
`underwear`, `costume`, `traditional`, `seasonal`), `color` and `fit`.

A famous character's outfit (the free library's anime and game cosplay, and any outfit recognised as one) has
`costume_character` and `costume_franchise`, and both are in its tags: `q=naruto` or `q=resident evil` finds it.

## Matching a character

Every outfit has `fit`: who it is cut for, `women`, `men` or `unisex`. To dress a character,
read its `gender` from [`GET /v1/characters`](https://docs.budgetpixel.com/api-reference/characters/list-characters-you-can-cast)
and pass it as `fit`: `fit=female` (or `women`) returns the women's outfits and the unisex ones.

```bash theme={null}
curl "https://api.budgetpixel.com/v1/wardrobe?fit=female&category=party" \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```

The wardrobe holds adult clothes only.

## One outfit in full

[`GET /v1/wardrobe/{handle}`](https://docs.budgetpixel.com/api-reference/wardrobe/get-an-outfit) returns the outfit with
`picture_url`, the full-size picture a mention sends, so you can use it with other tools too.
Every outfit's picture comes in three sizes: `thumbnail_url` (at most 350 px on its long side, for
a list or a grid), `preview_url` (at most 800 px) and `picture_url` (896×1200 for an outfit made
from a photo or a description; a clean picture keeps its own size). Links are signed and expire
after a few hours. When more than one of your outfits has the
handle, your own comes first, then a saved one, then the free library's: the same order a
mention follows.

## Add an outfit

[`POST /v1/wardrobe`](https://docs.budgetpixel.com/api-reference/wardrobe/add-an-outfit) adds clothes to your wardrobe from
a picture, a link or a description:

```bash theme={null}
curl https://api.budgetpixel.com/v1/wardrobe \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://shop.example.com/products/linen-shirt"}'
```

* `image_url` takes any picture's own address, one of your BudgetPixel pictures, or a shop's
  **product page**: the page is read once for the product picture and name it publishes for link
  previews.
* `image_data` takes the picture as base64; `description` designs the clothes from words.
* A link to a video post (a Reel, a TikTok) gives its cover picture. Reading the whole clip for
  its outfits is on the web for now (Add clothes, From a video).
* A picture of the clothes on their own is used as it is (**free**). When someone wears them
  (`mode: photo`), the clothes are taken out onto an invisible mannequin, and a description is
  designed (`mode: text`): both run an image model at its usual price, charged on success.

It answers `201` with the outfit when it is ready at once, or `202` with its `id` while its
picture is made (about a minute): [`GET /v1/wardrobe/{id}`](https://docs.budgetpixel.com/api-reference/wardrobe/get-an-outfit)
returns it once `status` is `ready`, with its final `@handle`.

> [!WARNING]
>
> Many shops don't allow automatic reading of their pages, ask for a login, or show no product
> picture (Amazon's pages, for one). Then the answer is `422` with `code: link_unreadable`, a
> `link_problem` and a message that says what to do instead: use the product picture's own
> address (right-click the picture, *Copy image address*) or send the picture itself. An agent
> that can browse can open the page and pass the picture's address.

## Making and sharing outfits

Make outfits in the [wardrobe](https://budgetpixel.com/wardrobe) on the web:

* **From a photo** of someone wearing it: the clothes are taken out onto an invisible
  mannequin, so any character can wear them. Name the piece you want when the photo shows
  more ("only the leather jacket").
* **From a description**: describe it and the outfit is designed for you.
* **From a clean picture**: a product shot that shows only the clothes, used as is.
* **From a link**: a shop's product page or a picture's address, read as above.
* **From a short video** of up to 30 seconds, uploaded or a link to a Reel, a TikTok or a YouTube
  Short: the outfits in it are found and each one is made (Auto, or the best 1 to 10).

Members on a paid plan can publish their outfits to the community, and anyone can save a
published outfit for free. A published outfit is checked before it appears: clothes on their own,
a clear picture, and words that match it. It reaches your prompts once you save it. Publishing is
permanent, so a saved outfit stays exactly as it was: its creator can't change or remove it (they
make a copy to edit instead), and only BudgetPixel takes one down.

The free library also has the AI influencers' signature outfits: `@barry_outfit` dresses any
character in Barry's look.

## Pricing and limits

* Listing and reading outfits is **free**: 300 list calls and 200 detail calls per day per
  account, at most 30 of each a minute. Adding outfits: 60 calls per day, 10 a minute. The API
  and MCP share these limits; past one, the answer is `429` with `Retry-After`.
* Wearing an outfit costs nothing extra: you pay for the image or video at the model's price,
  with the outfit's picture counted as a reference image where a model prices those.
  [`POST /v1/cost`](https://docs.budgetpixel.com/api-reference/models/estimate-the-cost-of-a-request) counts it.
* Making an outfit on the web from a photo or a description runs an image model at its usual
  price; a clean picture is free.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.