User Profile & Image

Before a user can generate a try-on, they need a usable base image: a clear, full-body-ish photo that has finished preprocessing. This page walks through the whole sequence — checking the profile, uploading a photo, confirming it, waiting for it to become ready, and displaying it back to the user.

Every endpoint on this page is user-scoped. Each request needs both headers:

x-api-key: <your_publishable_key> — identifies your store.
Authorization: Bearer <access_token> — the signed-in user’s session token from Authentication.

All requests and responses are JSON, with one exception: the direct upload (step 3) is a PUT of raw binary bytes to a signed storage URL.

The upload sequence

Check the profile

Call GET /user/profile. If has_base_image is false, the user has no photo yet and you should prompt for one.

Request a signed upload URL

Call POST /user/profile/upload-url with the file’s content type and size. You get back a short-lived upload_url and a storage path.

Upload the photo directly to storage

PUT the raw image bytes to upload_url. This goes straight to storage — it is not a call to the Souldi API.

Confirm the upload

Call PATCH /user/profile with the path from step 2. This kicks off background preprocessing and sets base_image_status to processing.

Poll until ready

Poll GET /user/profile until base_image_status is ready. Only then is the user ready to generate a try-on.

GET `/user/profile`

Fetch the authenticated user’s profile and the status of their base image. Use this both to decide whether the user needs to upload a photo and to poll preprocessing status. Required headers: x-api-key, Authorization: Bearer <access_token> This endpoint takes no body and no parameters.

curl https://api.souldi.io/user/profile \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch("https://api.souldi.io/user/profile", {
  headers: {
    "x-api-key": SOULDI_API_KEY,
    Authorization: `Bearer ${accessToken}`,
  },
});
const profile = await res.json();

Response fields

string

The user’s UUID.

string

The user’s email address.

boolean

true once the user has uploaded a base photo, false if they haven’t uploaded one yet. Pair it with base_image_status to know whether that photo is usable.

string

One of processing, ready, or rejected. Drives whether the user can generate (see Polling below).

200 OK

{
  "id": "9b1c0f2e-7a44-4c1e-9c2b-0f3a2d5e6f70",
  "email": "[email protected]",
  "has_base_image": true,
  "base_image_status": "ready"
}

The profile may also include optional body-measurement fields. These are secondary — they’re not required for the upload or generation flow, so you can safely ignore them.

POST `/user/profile/upload-url`

Get a short-lived signed URL that lets you upload a photo directly to storage, keeping the file off the Souldi API path entirely. Required headers: x-api-key, Authorization: Bearer <access_token>

Body parameters

Name	Type	Required	Description
`content_type`	string	Yes	The image MIME type. Must be `image/jpeg` or `image/png`.
`file_size_bytes`	integer	Yes	The file’s size in bytes. Maximum 15 MB (`15728640` bytes).

curl -X POST https://api.souldi.io/user/profile/upload-url \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "image/jpeg",
    "file_size_bytes": 482113
  }'

const res = await fetch(
  "https://api.souldi.io/user/profile/upload-url",
  {
    method: "POST",
    headers: {
      "x-api-key": SOULDI_API_KEY,
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content_type: file.type,
      file_size_bytes: file.size,
    }),
  },
);
const { upload_url, path } = await res.json();

Response fields

string

A pre-signed URL. PUT your raw image bytes here (step 3). It expires quickly, so upload right away.

string

The storage path of the uploaded file. Pass this to PATCH /user/profile to confirm the upload.

200 OK

{
  "upload_url": "https://storage.example.com/upload/signed?token=...",
  "path": "tenants/store_42/users/9b1c.../pending/base.jpg"
}

PUT `{upload_url}`

Upload the raw image bytes directly to storage using the upload_url from the previous step.

This PUT targets the signed storage URL returned above — not a Souldi API path. Do not send x-api-key or Authorization headers here; the signed URL already authorizes the upload.

Headers

Name	Value	Description
`Content-Type`	`image/jpeg` or `image/png`	Must match the `content_type` you sent when requesting the upload URL.

The request body is the raw binary file (not JSON, not multipart).

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

await fetch(upload_url, {
  method: "PUT",
  headers: { "Content-Type": file.type },
  body: file,
});

Storage returns a 200 or 201 on success with no JSON body to read. If the PUT fails, request a fresh upload_url and retry — signed URLs are short-lived.

PATCH `/user/profile`

Confirm the uploaded image and trigger preprocessing. This is what actually attaches the photo to the user’s profile. Required headers: x-api-key, Authorization: Bearer <access_token>

Body parameters

Name	Type	Required	Description
`path`	string	Yes	The storage `path` returned by `POST /user/profile/upload-url`.

curl -X PATCH https://api.souldi.io/user/profile \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "path": "tenants/store_42/users/9b1c.../pending/base.jpg" }'

const res = await fetch("https://api.souldi.io/user/profile", {
  method: "PATCH",
  headers: {
    "x-api-key": SOULDI_API_KEY,
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ path }),
});
const profile = await res.json();

The response is the updated profile, with base_image_status now processing.

200 OK

{
  "id": "9b1c0f2e-7a44-4c1e-9c2b-0f3a2d5e6f70",
  "email": "[email protected]",
  "has_base_image": true,
  "base_image_status": "processing"
}

Confirming kicks off background preprocessing — for example, removing the background and preparing the model image used for generation. The status becomes ready when it finishes, or rejected if the photo is unusable. You can call PATCH /user/profile again later with a new path to replace the photo.

GET `/user/signed_user_image_url`

Get a short-lived signed URL to display the user’s stored image in the browser — for example, to show their current photo before they generate. Required headers: x-api-key, Authorization: Bearer <access_token>

Query parameters

Name	Type	Required	Description
`variant`	string	No	Pass `no_bg` for the background-removed version. Omit for the original base image.

# Original base image
curl "https://api.souldi.io/user/signed_user_image_url" \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Background-removed variant
curl "https://api.souldi.io/user/signed_user_image_url?variant=no_bg" \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch(
  "https://api.souldi.io/user/signed_user_image_url",
  {
    headers: {
      "x-api-key": SOULDI_API_KEY,
      Authorization: `Bearer ${accessToken}`,
    },
  },
);
const { url } = await res.json();
imgEl.src = url; // short-lived — fetch fresh each time you display

Response fields

string

The user’s UUID.

string

A temporary signed URL pointing at the requested image. It has a short expiry, so request a fresh one each time you render rather than caching it.

200 OK

{
  "id": "9b1c0f2e-7a44-4c1e-9c2b-0f3a2d5e6f70",
  "url": "https://storage.example.com/render/signed?token=..."
}

Requesting variant=no_bg before preprocessing has produced the background-removed image returns 404. Wait until base_image_status is ready before requesting the no_bg variant.

Polling: wait for `ready`

After PATCH /user/profile, poll GET /user/profile until base_image_status is ready before attempting generation. A try-on request is rejected while the image is still processing, and a rejected status means the user must upload a different photo.

A simple polling loop, mirroring what the official widget does — it waits up to about 2 minutes, checking every few seconds:

Poll until ready

async function waitForReady({ intervalMs = 3000, maxWaitMs = 120000 } = {}) {
  const deadline = Date.now() + maxWaitMs;
  while (Date.now() < deadline) {
    const res = await fetch("https://api.souldi.io/user/profile", {
      headers: {
        "x-api-key": SOULDI_API_KEY,
        Authorization: `Bearer ${accessToken}`,
      },
    });
    const { base_image_status } = await res.json();

    if (base_image_status === "ready") return true;
    if (base_image_status === "rejected") {
      throw new Error("Photo rejected — ask the user for a new one.");
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error("Preprocessing timed out.");
}

Surface a friendly “preparing your photo…” state to the user while you poll. Most photos finish well within the window.

Next steps

Generate a try-on

Once base_image_status is ready, send garment URL(s) to start a try-on job and track it to completion.

Get Started

Try-On

Catalog Search

Sizes

User Profile & Image

The upload sequence

GET `/user/profile`

Response fields

POST `/user/profile/upload-url`

Body parameters

Response fields

PUT `{upload_url}`

Headers

PATCH `/user/profile`

Body parameters

GET `/user/signed_user_image_url`

Query parameters

Response fields

Polling: wait for `ready`

Next steps

Generate a try-on

​The upload sequence

​GET /user/profile

​Response fields

​POST /user/profile/upload-url

​Body parameters

​Response fields

​PUT {upload_url}

​Headers

​PATCH /user/profile

​Body parameters

​GET /user/signed_user_image_url

​Query parameters

​Response fields

​Polling: wait for ready

​Next steps

Generate a try-on

The upload sequence

GET `/user/profile`

Response fields

POST `/user/profile/upload-url`

Body parameters

Response fields

PUT `{upload_url}`

Headers

PATCH `/user/profile`

Body parameters

GET `/user/signed_user_image_url`

Query parameters

Response fields

Polling: wait for `ready`

Next steps