# Put a model in new poses

> Put the same person in the same clothes into new poses — picked from the pose library or described in words. Delivered as one image file per pose, in the order you listed them.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/image.repose` · **Task:** `image.repose` · **Scope:** `tasks:run` · **Category:** Image editing

Send a finished image and the poses you want — from your pose library or described in words — and get the same person in the same clothes in each pose. A pose that cannot be made is left out and not charged.

## Quick start

```python
import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/image.repose",
    headers=headers,
    json={
        "image": "art:9f2c01",
        "poses": {
            "type": "custom",
            "items": [
                {
                    "type": "library",
                    "pose": "pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80",
                },
                {
                    "type": "prompt",
                    "prompt": "arms crossed, looking over the left shoulder",
                },
                {
                    "type": "prompt",
                    "prompt": "walking towards the camera",
                },
            ],
        },
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())
```

```javascript
const headers = {
  Authorization: `Key ${process.env.REFABRIC_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch("https://api.refabric.com/v1/tasks/image.repose", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image": "art:9f2c01",
    "poses": {
      "type": "custom",
      "items": [
        {
          "type": "library",
          "pose": "pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80"
        },
        {
          "type": "prompt",
          "prompt": "arms crossed, looking over the left shoulder"
        },
        {
          "type": "prompt",
          "prompt": "walking towards the camera"
        }
      ]
    }
  }),
}).then((r) => r.json());
console.log(job.job_id);

let status = job;
while (status.lifecycle !== "terminal") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await fetch(job.status_url, { headers }).then((r) => r.json());
}

console.log(await fetch(job.result_url, { headers }).then((r) => r.json()));
```

```bash
curl -X POST "https://api.refabric.com/v1/tasks/image.repose" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"image":"art:9f2c01","poses":{"type":"custom","items":[{"type":"library","pose":"pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80"},{"type":"prompt","prompt":"arms crossed, looking over the left shoulder"},{"type":"prompt","prompt":"walking towards the camera"}]}}'
```

## Input schema

- `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — The finished image to re-pose; the person and the clothes are kept. As one string: a URL, a file from an earlier result (`art:…` or its url) or an upload (`file:…`). If it is one of your files placed in a project or on a design in the Refabric app, the result is filed there too.
  Example: `art:9f2c01`
- `poses` (object, _required_) — The poses to make, `{type: custom, items: [...]}` — 1 to 40 items, each a pose from the library (`{type: library, pose: "pose:<id>"}`, `GET /v1/refs/pose`) or in words (`{type: prompt, prompt}`). Every item is made and charged as one image.
  Example: `{"type":"custom","items":[{"type":"library","pose":"pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80"},{"type":"prompt","prompt":"arms crossed, looking over the left shoulder"},{"type":"prompt","prompt":"walking towards the camera"}]}`
- `model` (string, _optional_, pattern: ^model:.+$) — The model the image shows, as a `model:<id>` handle (`GET /v1/refs/model`). An image from a shoot, or an edit of one, already carries its model; send `model` for any other picture (an upload, a url).
  Example: `model:5501`

## Required-fields example

```json
{
  "image": "art:9f2c01",
  "poses": {
    "type": "custom",
    "items": [
      {
        "type": "library",
        "pose": "pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80"
      },
      {
        "type": "prompt",
        "prompt": "arms crossed, looking over the left shoulder"
      },
      {
        "type": "prompt",
        "prompt": "walking towards the camera"
      }
    ]
  }
}
```

## Full example

```json
{
  "image": "art:9f2c01",
  "poses": {
    "type": "custom",
    "items": [
      {
        "type": "library",
        "pose": "pose:112ea8bb-5c1d-4e0f-9a2b-3c4d5e6f7a80"
      },
      {
        "type": "prompt",
        "prompt": "arms crossed, looking over the left shoulder"
      },
      {
        "type": "prompt",
        "prompt": "walking towards the camera"
      }
    ]
  },
  "model": "model:5501"
}
```

## Output schema

- `files` (array<object>, _optional_) — One file per pose that was made, in `poses.items` order.
- `summary` (object, _optional_) — How many of the listed poses were made, and which are missing.
  - `requested` (integer, _optional_) — The poses listed.
  - `delivered` (integer, _optional_) — The files made (and charged).
  - `warnings` (array<object>, _optional_) — One `{code: "output_not_produced", field, message}` row per pose that could not be made, `field` naming it (`"poses.items[1]"`).

## Response example

```json
{
  "job_id": "d2b3c4d500004000800000000000000f",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000f",
  "result_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000f/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000f/cancel"
}
```

## Result example

```json
{
  "job_id": "d2b3c4d500004000800000000000000f",
  "files": [
    {
      "file": "art:9f2c07",
      "url": "https://files.example.com/image.repose/1.png",
      "media_type": "image/png",
      "task": "image.repose",
      "job_id": "d2b3c4d500004000800000000000000f",
      "created_at": "2026-10-01T09:40:02Z"
    },
    {
      "file": "art:9f2c09",
      "url": "https://files.example.com/image.repose/2.png",
      "media_type": "image/png",
      "task": "image.repose",
      "job_id": "d2b3c4d500004000800000000000000f",
      "created_at": "2026-10-01T09:40:19Z"
    }
  ],
  "has_more": false,
  "summary": {
    "requested": 3,
    "delivered": 2,
    "warnings": [
      {
        "code": "output_not_produced",
        "field": "poses.items[1]",
        "message": "One output of this job could not be produced; `field` names which."
      }
    ]
  }
}
```

Files come in `poses.items` order; here the second pose could not be made, so two files come back and a warning names the missing pose.

## Built for

- More poses from one shoot image
- A pose set for a product page
- Poses from your library applied to one look

## What you get

- One image per pose made, in the order you listed the poses.
- A `summary` that counts the poses asked for and made, and names each pose that could not be made.

## Specs

- **Input formats:** Images, each one string: a URL, an upload (`file:…`) or a file from an earlier result (`art:…`). Upload types and sizes: `GET /v1/meta` `limits.upload`.
- **Input count:** `image`: one
- **Output format:** Files: each one line with its `url` and its `media_type`, in the job's result.
- **Outputs per job:** One image file per item of `poses.items`.

## Choosing a task

- Use this when you have one finished image and want more poses of it. Use `photoshoot.create` when you are shooting garments on models from the start, with the poses chosen for the shoot.

## Errors

- `field_not_accepted`
- `invalid_request`
- `not_found`
- `permission_denied`
- `insufficient_credits`
- `content_refused`
- `processing_failed`
- `invalid_option`
- `field_not_supported`

## Related

- `pose.create` — It runs before: its result is this input.
- `photoshoot.create` — It runs before: its result is this input.
- `image.face_fix` — It runs after: it takes this task's result.

## Good to know

- `poses.items` holds at least 1 items.
- `poses.items` holds at most 40 items.

## For agents and code generation

- https://api.refabric.com/v1/tasks/image.repose/llms.txt
- https://api.refabric.com/v1/tasks/image.repose/openapi.json
- GET https://api.refabric.com/v1/tasks/image.repose