For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-apis/overview.md, and the index of every page is https://docs.refabric.com/llms.txt.
Task APIs
Task APIs
Every Refabric task is called the same way: send its input, get a job, read the job's files.
A task is one piece of fashion work with a name — image.generate, image.change_background,
photoshoot.create. Its input and output are published as JSON Schema in the catalogue
(GET /v1/tasks/{name}) and on its page in the Task API Reference.
A task call does not answer with the result. It starts a job, and the job delivers files: images, videos, SVGs, PDFs or a record. You choose how to learn that the job has ended.
Quick example
import os, time, requests
API = "https://api.refabric.com/v1"
s = requests.Session()
s.headers["Authorization"] = f"Key {os.environ['REFABRIC_API_KEY']}"
job = s.post(f"{API}/tasks/image.generate", json={"prompt": "a navy linen shirt dress, studio photo"}).json()
while (status := s.get(job["status_url"]).json())["lifecycle"] != "terminal":
time.sleep(5)
print(s.get(job["result_url"]).json()["files"])Every task follows the same pattern: POST /v1/tasks/{name} answers 202 with a job_id and its
status_url, result_url and cancel_url; the job's result lists its files in one shape
(Files and media). Only the input differs from task to task.
How it works
| Way | How | When |
|---|---|---|
| Submit and poll | read status_url until lifecycle is terminal, then result_url | the default; works everywhere (Asynchronous jobs) |
| Wait | send Prefer: wait=N; a job that ends in time answers 200 with its result | short jobs (Synchronous) |
| Webhook per job | add ?webhook_url= to the submit; we call you when the job ends | one-off jobs whose caller can receive a POST (Webhooks) |
| Registered webhook endpoints | register an endpoint once in Panel › Developers › Webhooks | every job started with your keys; progress events too (Webhooks) |
Before you submit, POST /v1/tasks/{name}/estimate with the same body tells you the most the job can
cost (Pricing).
What you can make
The catalogue groups its tasks by category (category on every task). The categories, what each
one makes and its tasks are listed live on All tasks; the category values
are the task_category vocabulary.