Assets
Manage the uploaded images you reuse across jobs
An asset is an uploaded image stored in your library so you can browse, tag, reuse, and clean up the images you work with.
Every image you send through POST /upload becomes an asset. The file_id returned by the upload is the same identifier you pass to a service through the images field, so your library and your jobs stay connected.
Key fields
| Field | Description |
|---|---|
id | Stable identifier for the asset. |
filename | Original filename of the uploaded image. |
url | URL used to access the full image. |
thumbnail_small, thumbnail_big | Convenience thumbnail URLs, when available. |
dimensions | [width, height] in pixels, when available. |
tags | Labels applied to the asset, drawn from a fixed set. |
visibility | Who can see the asset: private, shared, or default. |
styling_note | Free-form styling instruction kept with the asset. |
created_by | Username of the uploader. |
created_at | ISO 8601 timestamp of when the asset was created. |
Tags
Tags help you group and filter your library. Each asset accepts up to 10 tags, chosen from a fixed set:
| Tag | Typical use |
|---|---|
model | Photos of a person or model. |
product | Standalone product or garment shots. |
background | Scenes and backdrops. |
other | Anything that does not fit the above. |
Only the owner of an asset can change its tags. When listing assets you can narrow results with include_tags (keep assets that have all of the listed tags) and exclude_tags (drop assets that have any of the listed tags).
Visibility and sharing
Visibility controls who can see an asset, and lines up with the ownership filter on the list endpoint.
| Value | ownership filter | Who can see it |
|---|---|---|
private | mine | Only you. |
shared | shared | You and the other members of your group. |
default | default | Everyone, provided by the platform. |
If you belong to a group, listing with ownership=shared surfaces assets uploaded by your teammates alongside your own.
Styling notes
An asset can carry a free-form styling_note: a short instruction such as "keep the sleeves rolled up" that you want remembered for this image. Set or clear it with the styling note endpoint. Sending an empty value removes it. The note is pre-filled in the picker the next time you reuse the asset in a job, so recurring guidance follows the image instead of being retyped.
Detected attributes
When an image is uploaded, the platform can attach a set of auto-detected attributes under detected. These are best-effort hints and may be absent for older or ambiguous images.
| Field | Description |
|---|---|
has_person | Whether a person was detected in the image. |
has_clothing | Whether clothing was detected in the image. |
person_attributes | High-level descriptors of a detected person, such as Adult or Female. |
clothing_items | Detected garments, such as Shirt or Pants. |
categories | Broad content categories, such as Apparel and Accessories. |
Good to know
- Only the original uploader can delete an asset. You can remove a single asset or delete in bulk, up to 100 assets per request.
- Bulk deletion is rate limited to 3 requests per second. Exceeding it returns
429 Too Many Requests. A bulk delete reports how many assets were removed and lists any that could not be deleted. - Listing assets is paginated, with up to 100 results per page, and
searchmatches against tags, filename, and project name. - Storing assets does not consume credits. Credits are spent when you run a job or extract a preset, not when you upload or keep images.
Where assets are used
Uploaded assets are the starting point for the main services:
- Model swap
- Flat lay on model
- Create an identity (as reference images through
input_assets)
API endpoints
Upload an image POST
/uploadGet paginated list of image assets GET
/assetsGet a single asset by ID GET
/assets/{asset_id}Update asset tags PATCH
/assets/{asset_id}/tagsUpdate asset styling note PATCH
/assets/{asset_id}/noteDelete a single asset by ID DELETE
/assets/{asset_id}Bulk delete assets POST
/assets/bulk-delete