> ## 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. # Poses > Put any character in a chosen body pose from your code or AI agent. Write the pose's @handle after the character in an image or video prompt. A shared library of poses drawn on two faceless mannequins, each one doable by a real body. A pose is a body position drawn on two faceless grey mannequins, a woman and a man, from the front and from other angles. Write its `@handle` after a [character](https://docs.budgetpixel.com/characters.md) in a prompt and the character takes that position: the mannequin's picture goes with the mention as a reference image, and the pose's description is added to the prompt. The character keeps their own face, build and clothes. ```bash theme={null} curl https://api.budgetpixel.com/v1/images/seedream-5.0-pro \ -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "@rosa in @sitting_knee_up_pose on a beach at sunset, full-body photo"}' ``` Every pose in the library is one a real body can do: each one is checked for joints, balance and what holds the body up before it joins. You'll find everyday poses, athletic ones (splits, handstands, yoga) and glamour poses; contortion and sex positions are not in the library. The library is shared, so every pose works for every user, and you can [design new poses](#design-a-pose) that join it. > [card] [The pose library](https://budgetpixel.com/poses) > > Browse every pose by shelf, see its handle and its pictures from every angle. > [!NOTE] > > Available on **every paid plan**, like the rest of the API. Over [MCP](https://docs.budgetpixel.com/mcp-server.md), your > agent finds poses with `search_poses` and `get_pose`, designs new ones with `design_pose` and > `check_pose_design`, makes new views with `make_pose_view` and `check_pose_view`, and poses a > character with the same @mention in `generate_image` or `generate_video`. ## The two mannequins Every pose is drawn twice: on a woman and on a man, both faceless and grey, with adult proportions. A mention sends the one that matches the character's gender, so a female character gets the woman and a male character the man. When the gender isn't known, the woman is sent. Each figure is drawn from the front and from other angles: three-quarter, side, from above and from below, and from behind on poses that are about the back. A designed pose has the front and three-quarter views. Anyone can add a view from another place around the figure, and it joins the library for everyone: see [Views from other angles](#views-from-other-angles). ## Posing a character * Write the character, then the pose: `"@rosa in @sitting_knee_up_pose on a beach at sunset"`. A pose goes with the nearest character written before it, so with two people, write a pose after each of them. Up to **4 poses** per generation; their pictures count as reference images. * Add a view to the mention to choose the angle: `@sitting_knee_up_pose.three_quarter`. `front` is the default. Every picture in a pose's `pictures` carries its own `mention`, so the pictures show the views you can ask for. A view the pose doesn't have yet uses its nearest picture; [make the view](#views-from-other-angles) for the exact angle. * Only the position carries over: where the torso, head, arms, hands, legs and feet are, which way the body faces, and what touches the floor or a seat. The mannequin's build, blank face, lines and grey colour never do. * Dress the character too with an [outfit](https://docs.budgetpixel.com/wardrobe.md): `"@barry wearing @camel_belted_overcoat_outfit in @sitting_knee_up_pose"`. * A pose works on the models that take characters (see `supported_models` on [`GET /v1/characters/{handle}`](https://docs.budgetpixel.com/api-reference/characters/get-a-character)), in image and video prompts. The mannequin's picture is a reference image, like a character's picture. ## Find a pose ```bash theme={null} curl "https://api.budgetpixel.com/v1/poses?q=knee&shelf=sitting" \ -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" ``` ```json theme={null} { "poses": [ { "id": "6f1c2a9e-…", "handle": "sitting_knee_up_pose", "mention": "@sitting_knee_up_pose", "name": "Sitting Knee Up", "slug": "sitting-knee-up-pose", "description": "Sits on the floor leaning back, the weight on both palms placed flat behind the hips. One knee is bent up towards the chest, the other leg stretched out straight and relaxed. The torso angles slightly back and the head faces forward.", "shelf": "sitting", "shelf_label": "Sitting", "tags": ["floor", "relaxed", "casual"], "support": "sitting", "props": [], "difficulty": "everyday", "holdable": true, "fit": "unisex", "rating": 0, "uses": 128, "source": "house", "creator": null, "created_at": "2026-11-03T12:00:00Z", "cover": { "id": "…", "figure": "woman", "angle": "front", "url": "https://…", "thumbnail_url": "https://…", "width": 864, "height": 1152, "azimuth": 0, "elevation": 0, "label": "Front", "view": false, "mention": "@sitting_knee_up_pose" }, "pictures": [ { "id": "…", "figure": "woman", "angle": "front", "url": "https://…", "thumbnail_url": "https://…", "width": 864, "height": 1152, "azimuth": 0, "elevation": 0, "label": "Front", "view": false, "mention": "@sitting_knee_up_pose" }, { "id": "…", "figure": "woman", "angle": "three_quarter", "url": "https://…", "thumbnail_url": "https://…", "width": 864, "height": 1152, "azimuth": 315, "elevation": 0, "label": "Three-quarter", "view": false, "mention": "@sitting_knee_up_pose.three_quarter" }, { "id": "…", "figure": "man", "angle": "front", "url": "https://…", "thumbnail_url": "https://…", "width": 864, "height": 1152, "azimuth": 0, "elevation": 0, "label": "Front", "view": false, "mention": "@sitting_knee_up_pose" } ], "view_count": 2 } ], "total": 1, "has_more": false, "shelves": [{ "id": "standing", "label": "Standing" }, { "id": "sitting", "label": "Sitting" }, …], "how_to_use": "Write @handle in the prompt of any image or video generation …" } ``` [`GET /v1/poses`](https://docs.budgetpixel.com/api-reference/poses/list-poses) searches the library. Filter with `q` (words that must all appear in the name, handle, description or tags), `shelf` and `fit`, and page with `limit` (20 by default, at most 50) and `offset`: `total` counts every match and `has_more` says whether there are more. | `shelf` | Holds | | - | - | | `standing` | Standing | | `sitting` | Sitting | | `lying` | Lying | | `kneeling_crouching` | Kneeling and crouching | | `walking_running` | Walking and running | | `jumping_action` | Jumps, landings and action | | `dance` | Dance | | `sports_fitness` | Sports, yoga and workouts | | `glamour` | Glamour | | `gestures_upper_body` | Gestures and upper-body poses | Each pose also says how hard it is (`difficulty`: `everyday` or `athletic`), whether a person can hold it still for a photo (`holdable`; `false` for a moment in motion, like a jump), what holds the body up (`support`), the `props` it needs, and `fit`: who it is made for (`women`, `men` or `unisex`). `fit=women` (or `men`) lists the poses made for women (or men) and the unisex ones. Every pose works for any character, because the mannequin follows the character's gender. ## One pose in full [`GET /v1/poses/{handle}`](https://docs.budgetpixel.com/api-reference/poses/get-a-pose) returns `{ "pose": { … } }`: the description word for word (the text a mention adds to the prompt) and every mannequin picture by `figure` (`woman`, `man`) and place, each with `url`, `thumbnail_url`, `width`, `height`, its place on the globe (`azimuth`, `elevation` and a `label` such as `"Back left · from above"`) and the `mention` that asks for it. The handle works with or without the `@`. A list carries each pose's own pictures and a `view_count`. This answer carries every view members made too, each with `view: true` and the username of the member who made it in `made_by`. ## Views from other angles A pose can be seen from any place on the Camera Angles globe. When the view you need isn't in a pose's `pictures` yet, ask for it: the mannequin's front picture is turned to that place, a check confirms it is still the same pose and where the camera landed, and the view joins the library for everyone, credited to you. There are no private views. ```bash theme={null} curl https://api.budgetpixel.com/v1/poses/seiza_pose/views \ -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"figure": "woman", "azimuth": 135, "elevation": 30}' ``` ```json theme={null} { "status": "making", "joined": false, "price": 40, "job": { "id": "0b6f4d1e-…", "pose_id": "…", "figure": "woman", "azimuth": 135, "elevation": 30, "angle": "az135_el30", "label": "Back right · from above", "status": "queued", "message": "", "attempts": 0, "credits_charged": 0, "created_at": "2026-11-03T18:00:00Z", "updated_at": "2026-11-03T18:00:00Z" } } ``` `figure` is the mannequin to turn (`woman` or `man`; a mention sends the one that matches the character's gender). `azimuth` is where the camera stands around the figure, and `elevation` how high: `0` eye level, `30` from above, `60` from high above. | `azimuth` | The camera stands | Mention at eye level | | - | - | - | | `0` | In front | `@seiza_pose` | | `45` | Front right | `@seiza_pose.front_right` | | `90` | Right side: the camera moved to the viewer's right, so the figure's left side shows | `@seiza_pose.right` | | `135` | Back right | `@seiza_pose.back_right` | | `180` | Behind | `@seiza_pose.back` | | `225` | Back left | `@seiza_pose.back_left` | | `270` | Left side | `@seiza_pose.left` | | `315` | Front left, where the pose's own three-quarter picture sits | `@seiza_pose.three_quarter` | In front, `.above` asks for elevation `30` and `.top` for `60`. The other raised places are named by a code: `@seiza_pose.az135_el30`. Each view's `mention` in the pose's `pictures` is always the right one to write. * [`POST /v1/poses/{handle}/views`](https://docs.budgetpixel.com/api-reference/poses/make-a-pose-view) answers `200` with `status: "made"` and the `picture` when the place already has a view, for free. Otherwise it answers `202` with `status: "making"` and the `job`. * Follow the job with [`GET /v1/poses/views/{id}`](https://docs.budgetpixel.com/api-reference/poses/get-a-pose-view-job) every 10 to 15 seconds. A view usually takes 30 to 90 seconds, through `queued` and `working` to `done`, with the view in `picture`. A `missed` job didn't come out right after two tries, and a `failed` one says what happened in `message`; neither is charged. * One job per place: when someone is already making the view you ask for, you join their job (`joined: true`) and pay nothing. * A try that lands on another empty place is kept there for everyone, free, in `landed_picture`. * **40 credits** per view, charged only when it lands where you asked; the second try is free. Up to 50 new views a day (`429` with `error_code: daily_cap` past that); `402` with `error_code: insufficient_credits` when your credits can't cover it. ## Design a pose When the library doesn't have the pose you need, design it: describe it in words, or start from a library pose and say what to change. Every pose made joins the shared library for everyone, with you as its creator; there are no private poses. ```bash theme={null} curl https://api.budgetpixel.com/v1/poses/designs \ -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"words": "sitting on a high stool, one foot on the rung, the other leg straight, hands on the front knee, looking over the left shoulder"}' ``` * `words` describe the pose head to toe, in up to 600 characters. With `parent_pose_id` (a library pose's handle or id), they say what to change: `"the left arm raised higher"`. * When library poses already look like the request, [`POST /v1/poses/designs`](https://docs.budgetpixel.com/api-reference/poses/design-a-pose) answers `200` with them in `matches` and starts nothing: use one, or send the request again with `"confirm": true`. * Otherwise it answers `201` with the `design`. Follow it with [`GET /v1/poses/designs/{id}`](https://docs.budgetpixel.com/api-reference/poses/get-a-pose-design) every 20 to 30 seconds. It takes about 3 to 6 minutes, through `queued` and `working` (`stage_label` says what it is doing) to `done`, with the new `pose` and its handle. A `refused` design says why in `message` and offers a doable alternative in `suggestion`; a `failed` one says what happened. * Every pose must be one a real body can do: poses a body can't hold, contortion, sex positions, minors, real people and violence are refused. * **100 credits** per pose, charged only when it is made: a refused or failed design is free. Paid plans only, up to 20 designs a day (`429` past that); `402` with `error_code: insufficient_credits` when your credits can't cover it. ## Over MCP Connect the [MCP server](https://docs.budgetpixel.com/mcp-server.md) and ask in plain words: *"Put @rosa in a sitting pose with one knee up, on a beach at sunset."* The agent calls `search_poses` (by words, shelf or `fit`) and gets a short list of poses, each with its mention, shelf, difficulty, a line of description and its front picture. `get_pose` reads one pose in full, with every picture and how to write it in a prompt. Then the agent writes `"@rosa in @sitting_knee_up_pose …"` in `generate_image` or `generate_video`, with an angle when you ask for one. When nothing fits, `design_pose` designs a new pose (showing the library poses that already look like it first), and `check_pose_design` follows it until its handle is ready. When a pose lacks the angle you want, `make_pose_view` makes that view for everyone and `check_pose_view` follows it until its mention is ready: *"Show @rosa in the seiza pose from behind and a little above."* ## On the web Browse the [pose library](https://budgetpixel.com/poses) by shelf. **Pose** on your character's page, or in Try-on, puts the character in a library pose and keeps the result as one of the character's pictures, tagged with the pose: `@mina.sitting_knee_up_pose` then casts that exact picture, like any of a [character's](https://docs.budgetpixel.com/characters.md) tagged pictures. ## Pricing and limits * Listing and reading poses is **free**: 300 list calls and 200 detail calls per day per account, at most 30 of each a minute. The API and MCP share these limits; past one, the answer is `429` with `Retry-After`. * Using a pose adds no fee: you pay the model's normal price for the image or video. * Designing a pose costs **100 credits**, charged only when the pose is made; paid plans, up to 20 designs a day. * A new view costs **40 credits**, charged only when it lands where you asked; joining a view someone is already making is free. Up to 50 new views a day. Following a view job is free. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.