Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-api-reference/image.repose.md, and the index of every page is https://docs.refabric.com/llms.txt.

Image editing

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.reposeTask: image.reposeScope: tasks:runCategory: Image editing

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

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

    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.

    pattern: ^(https://|art:|file:).+$

    Example: art:9f2c01

  • objectrequired

    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"}]}

  • stringoptional

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

    pattern: ^model:.+$

    Example: model:5501

Output schema

  • array<object>optional

    One file per pose that was made, in poses.items order.

  • objectoptional

    How many of the listed poses were made, and which are missing.

Required-fields example

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

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

Response example

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

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

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.

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 formatsImages, 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 countimage: one
Output formatFiles: each one line with its url and its media_type, in the job's result.
Outputs per jobOne image file per item of poses.items.

Choosing a task

Errors

Related

Good to know

  • poses.items holds at least 1 items.
  • poses.items holds at most 40 items.

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

For agents and code generation

Schema changes follow Versioning.