# Add a pose

> Turn a photo of a person posing into a pose in your library, to shoot or re-pose models in. The result is the pose, pose:<id>.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/pose.create` · **Task:** `pose.create` · **Scope:** `tasks:run` · **Category:** Records & libraries

Send a photo of a person posing and get a pose in your library — its framing, its camera angle and what the body does — so a shoot or a re-pose can put your models in it.

## 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/pose.create",
    headers=headers,
    json={
        "image": "https://cdn.example.com/lookbook/pose-walk.jpg",
        "gender": "woman",
    },
).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/pose.create", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image": "https://cdn.example.com/lookbook/pose-walk.jpg",
    "gender": "woman"
  }),
}).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/pose.create" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"image":"https://cdn.example.com/lookbook/pose-walk.jpg","gender":"woman"}'
```

## Input schema

- `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — A photo of ONE person (or one object) in the pose, as one string: a public `https://` URL, a file from an earlier result (`art:…` or its url) or an upload (`file:…`).
  Example: `https://cdn.example.com/lookbook/pose-walk.jpg`
- `gender` (string, _required_) — Who is pictured: the person a pose or a model shows.
  Values: `woman` (An adult woman. When the person pictured is an adult woman.); `man` (An adult man. When the person pictured is an adult man.); `girl` (A girl (a child). When the person pictured is a girl.); `boy` (A boy (a child). When the person pictured is a boy.)
  Example: `woman`

## Required-fields example

```json
{
  "image": "https://cdn.example.com/lookbook/pose-walk.jpg",
  "gender": "woman"
}
```

## Full example

```json
{
  "image": "https://cdn.example.com/lookbook/pose-walk.jpg",
  "gender": "woman"
}
```

## Output schema

- `files` (array<object>, _optional_) — ONE file: the pose, `pose:<id>` — its `url` is the pose image. Pass the handle to `image.repose` or `photoshoot.create` (`poses`); `GET /v1/refs/pose` lists it with your other poses.

## Response example

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

## Result example

```json
{
  "job_id": "7c1e2d3f4a5b4c6d8e9f0a1b2c3d4e5f",
  "files": [
    {
      "file": "pose:7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "url": "https://files.example.com/pose.create/1.jpg",
      "media_type": "image/jpeg",
      "task": "pose.create",
      "job_id": "7c1e2d3f4a5b4c6d8e9f0a1b2c3d4e5f",
      "created_at": "2026-10-01T09:12:04Z"
    }
  ],
  "has_more": false
}
```

`url` is the pose image. Pass `pose:<id>` to image.repose or photoshoot.create; GET /v1/refs/pose lists your poses.

## Built for

- Your own poses for photoshoots
- Re-posing a model into a pose you choose
- A brand's signature stances, kept in one library

## What you get

- One `pose:` file in your library, its `url` the pose image; pass the handle to `image.repose` or `photoshoot.create` in `poses`.

## 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:** One `pose:` file, an image: its `url` is the picture and its `media_type` the image's type; it carries no `data`.
- **Outputs per job:** One library file: the pose.

## Errors

- `field_not_accepted`
- `invalid_request`
- `invalid_option`
- `image_not_public`
- `not_found`
- `permission_denied`
- `processing_failed`

## Related

- `image.repose` — It runs after: it takes this task's result.
- `photoshoot.create` — It runs after: it takes this task's result.
- `background.create` — It does a neighbouring job.

## For agents and code generation

- https://api.refabric.com/v1/tasks/pose.create/llms.txt
- https://api.refabric.com/v1/tasks/pose.create/openapi.json
- GET https://api.refabric.com/v1/tasks/pose.create