Records & libraries

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.createTask: pose.createScope: tasks:runCategory: Records & libraries

Quick start

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())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

stringrequired
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:…).
pattern: ^(https://|art:|file:).+$
Example: https://cdn.example.com/lookbook/pose-walk.jpg
stringrequired
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

Output schema

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.

Required-fields example

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

Full example

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

Response example

{
  "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

{
  "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.

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.

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

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.

Good to know

Pricing: Estimate a request before you run it, or see the price of each option.

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

Schema changes follow Versioning.