Skip to content
Figur

Getting started

The Figur API is an AI fashion-imagery engine. You send one request to dispatch a workflow — virtual try-on, product-to-model, model / background / garment generation, background or model swap, garment extraction, or a look composite — and the engine renders the result asynchronously. Every workflow is a peer over a single job model, so the lifecycle below is identical no matter which one you call.

For the full, per-field reference of every endpoint, open the API reference. This guide only covers the lifecycle and a minimal example.

The lifecycle: dispatch → poll events → fetch render

Section titled “The lifecycle: dispatch → poll events → fetch render”
  1. Dispatch. POST to a workflow endpoint (for example POST /v1/try-on) with a typed JSON body. The call returns 202 Accepted immediately with a job_id, a status, the credits_cost that was deducted, and a request_id. The render is not ready yet.
  2. Poll the event stream. GET /v1/jobs/{public_id}/events?since={seq} returns the job’s event timeline as a cursored stream. Each event has a monotonic seq (your next ?since= cursor), an event_type (queued → stage → succeeded / failed), and may carry presigned artifacts. Re-poll, passing the last latest_seq you saw, until you receive a succeeded or failed event.
  3. Fetch the result. When the job succeeds, read the final manifest from GET /v1/jobs/{public_id} (its result carries the output artifacts and latest_event), or pull the finished image from the cross-job gallery via GET /v1/renders/{public_id}. The render’s identity is the originating job’s ULID.

You can also list jobs with GET /v1/jobs, cancel an in-flight job with POST /v1/jobs/{public_id}/cancel, and browse all finished renders with GET /v1/renders.

Minimal end-to-end example (curl)

Section titled “Minimal end-to-end example (curl)”

Dispatch a try-on of one garment onto a user photo:

Terminal window
curl -sS -X POST https://api.figur.fit/v1/try-on \
  -H "Authorization: Bearer $FIGUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_image": "users/abc/user.jpg",
    "items": [
      { "trial_image": "users/abc/trial/shirt-1.jpg", "trial_item_category": "top" }
    ]
  }'

Response (202 Accepted):

{
  "request_id": "01JREQREQREQREQREQREQREQ00",
  "job_id": "01JJOBJOBJOBJOBJOBJOBJOB00",
  "status": "NOT_STARTED",
  "credits_cost": 10
}

Poll until the job reaches a terminal event:

Terminal window
curl -sS "https://api.figur.fit/v1/jobs/01JJOBJOBJOBJOBJOBJOBJOB00/events?since=0" \
  -H "Authorization: Bearer $FIGUR_API_KEY"

When you see a succeeded event, fetch the render:

Terminal window
curl -sS "https://api.figur.fit/v1/renders/01JJOBJOBJOBJOBJOBJOBJOB00" \
  -H "Authorization: Bearer $FIGUR_API_KEY"

With the TypeScript SDK

Section titled “With the TypeScript SDK”

The @figur/sdk package wraps the same surface, generated from openapi.json. Its run() helper dispatches a workflow, polls the event stream to a terminal state, and returns the finished render in one call:

import { Figur } from '@figur/sdk'


const figur = new Figur({ apiKey: process.env.FIGUR_API_KEY! })


const render = await figur.run('try-on', {
  user_image: 'users/abc/user.jpg',
  items: [{ trial_image: 'users/abc/trial/shirt-1.jpg', trial_item_category: 'top' }],
})


console.log(render) // the finished render for the succeeded job

Next

Section titled “Next”