API reference

Tasks

An image-generation job. Two families share one shape: beautifier (the Product beautifier) renders the product alone on a background, tryon (the photo shoot) renders it on a model. Both move queued → running → succeeded or failed and deliver a task.* webhook at the end.

Endpoints

GET/v1/tasks
POST/v1/tasks/beautifier
POST/v1/tasks/edit
POST/v1/tasks/tryon
GET/v1/tasks/{task_id}

The Task object

Attributes

idstring
Crockford-base32 ULID (26 chars).
typeenum
- beautifier
- tryon
- edit
subtypeenum, nullable
- clothing
- shoes
- headwear
- glasses
- bags
statusenum
- queued
- processing
- completed
- failed
product_idstring
Crockford-base32 ULID (26 chars).
inputsobject
What the task was created with, as you sent it (BeautifierInputs for beautifier tasks, TryonInputs for tryon tasks, EditInputs for edits). Model and background come back as their public ids and slugs.
Show child attributesHide child attributes
- product_idstring
  Crockford-base32 ULID (26 chars).
- backgroundstring
  Slug from the beautifier backgrounds catalogue (https://api.veeton.com/reference/catalogues/beautifier/backgrounds). Hex-coded slugs include the leading # (e.g. "#ffffff").
- angle_shotstring
  Allowed values depend on subtype; see the beautifier angle-shots catalogue (https://api.veeton.com/reference/catalogues/beautifier/angle-shots).
- styleenum
  - ghost_mannequin
  - flatlay
output_imageobject, nullable
Show child attributesHide child attributes
- idstring
  Stable image id; GET /v1/images/{id} re-signs it.
- mime_typeenum
  - image/jpeg
  - image/png
  - image/webp
- widthinteger, nullable
  Pixel width, null when not yet known.
- heightinteger, nullable
- urlstring (URL)
  Time-limited signed URL to the bytes. Fetch a fresh one from GET /v1/images/{id} when it expires.
- url_expires_attimestamp
  When url stops working.
- created_attimestamp
  Upload time for your photos, task completion for generations.
quality_checkobject
Show child attributesHide child attributes
- statusenum
  not_checked — no check has run (yet, or ever: only try-ons are checked). passed — checked, nothing flagged. flagged — at least one finding.
  - not_checked
  - passed
  - flagged
- checked_attimestamp, nullable
  When the check ran; null while not_checked.
- findingsarray of objects
  Show child attributesHide child attributes
  - kindstring
    What was flagged, e.g. garbled_text, distorted_logo, duplicated_object. Open list: ignore kinds you do not know.
  - boxarray of numbers, nullable
    Where on output_image, as [x0, y0, x1, y1] fractions of its width and height; null when not localised.
failure_reasonobject, nullable
Show child attributesHide child attributes
- codestring
- messagestring
started_attimestamp, nullable
RFC 3339 / ISO 8601 timestamp.
finished_attimestamp, nullable
RFC 3339 / ISO 8601 timestamp.
created_attimestamp
RFC 3339 / ISO 8601 timestamp.

The Task object

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
  "type": "beautifier",
  "subtype": "clothing",
  "status": "queued",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "inputs": {
    "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "background": "wood",
    "angle_shot": "front",
    "style": "ghost_mannequin"
  },
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
    "mime_type": "image/jpeg",
    "width": 1,
    "height": 1,
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z",
    "created_at": "2026-04-27T14:32:00Z"
  },
  "quality_check": {
    "status": "not_checked",
    "checked_at": "2026-04-27T14:32:00Z",
    "findings": [
      {
        "kind": "garbled_text",
        "box": [
          1
        ]
      }
    ]
  },
  "failure_reason": {
    "code": "task_failed",
    "message": "string"
  },
  "started_at": "2026-04-27T14:32:00Z",
  "finished_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z"
}

List tasks

GET/v1/tasks

Cursor-paginated list of the caller's tasks (beautifier, tryon and edit). Newest-first.

Use this primarily for reconciliation after webhook downtime — the canonical "tell me when my task finishes" channel is webhook delivery. For steady-state operation, register a webhook at POST /v1/webhooks and react to terminal events as they arrive.

Filters:

status — queued, processing, completed, failed.
type — beautifier, tryon or edit.
subtype — clothing, shoes, headwear, glasses, bags. Implicitly narrows to beautifier (tryon and edit have no subtype).
product_id — only tasks referencing this product.

Parameters

limitinteger· queryoptional
Default : 25
cursorstring· queryoptional
statusenum· queryoptional
- queued
- processing
- completed
- failed
typeenum· queryoptional
- beautifier
- tryon
- edit
subtypeenum, nullable· queryoptional
- clothing
- shoes
- headwear
- glasses
- bags
product_idstring· queryoptional
Crockford-base32 ULID (26 chars).

Returns

Returns a TaskList object with status 200.

Errors

400
Invalid request
500
Server error

GET/v1/tasks

curl https://api.veeton.com/v1/tasks \
  -H "Authorization: Bearer $VEETON_KEY"
import requests

response = requests.get(
    "https://api.veeton.com/v1/tasks",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/tasks", {
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
})

const data = await response.json()

Response · 200

{
  "data": [
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
      "type": "beautifier",
      "subtype": "clothing",
      "status": "queued",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "inputs": {
        "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
        "background": "wood",
        "angle_shot": "front",
        "style": "ghost_mannequin"
      },
      "output_image": {
        "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
        "mime_type": "image/jpeg",
        "width": 1,
        "height": 1,
        "url": "https://example.com/…",
        "url_expires_at": "2026-04-27T14:32:00Z",
        "created_at": "2026-04-27T14:32:00Z"
      },
      "quality_check": {
        "status": "not_checked",
        "checked_at": "2026-04-27T14:32:00Z",
        "findings": [
          {
            "kind": "garbled_text",
            "box": []
          }
        ]
      },
      "failure_reason": {
        "code": "task_failed",
        "message": "string"
      },
      "started_at": "2026-04-27T14:32:00Z",
      "finished_at": "2026-04-27T14:32:00Z",
      "created_at": "2026-04-27T14:32:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6InByb2RfMDFIWCJ9",
  "has_more": true
}

Create a beautifier task

POST/v1/tasks/beautifier

Queues one beautifier task — a clean product render — and returns 202 immediately. The terminal state (completed / failed) is delivered to your registered webhook(s); GET /v1/tasks/{id} is available as a fallback. Strongly recommended: send Idempotency-Key to make retries safe.

subtype selects the flow (clothing, shoes, headwear, glasses or bags); each has its own input rules, see https://api.veeton.com/guides/tasks.

Accepted slugs, with previews, are in the Product beautifier catalog: Backgrounds, Angle shots and Styles.

Parameters

subtypeenum, nullablerequired
- clothing
- shoes
- headwear
- glasses
- bags
inputsobjectrequired
Show child attributesHide child attributes
- product_idstringrequired
  Crockford-base32 ULID (26 chars).
- backgroundstringrequired
  Slug from the beautifier backgrounds catalogue (https://api.veeton.com/reference/catalogues/beautifier/backgrounds). Hex-coded slugs include the leading # (e.g. "#ffffff").
- angle_shotstringrequired
  Allowed values depend on subtype; see the beautifier angle-shots catalogue (https://api.veeton.com/reference/catalogues/beautifier/angle-shots).
- styleenumoptional
  - ghost_mannequin
  - flatlay

Returns

Returns a Task object with status 202.

Errors

400
Invalid request
402
No active subscription / insufficient credits
404
Product not found
422
Subtype/inputs mismatch or required image missing
500
Server error
502
Upstream queue unavailable

POST/v1/tasks/beautifier

curl https://api.veeton.com/v1/tasks/beautifier \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subtype": "clothing",
  "inputs": {
    "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "background": "wood",
    "angle_shot": "front",
    "style": "ghost_mannequin"
  }
}'
import requests

response = requests.post(
    "https://api.veeton.com/v1/tasks/beautifier",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    json={
          "subtype": "clothing",
          "inputs": {
            "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
            "background": "wood",
            "angle_shot": "front",
            "style": "ghost_mannequin"
          }
        },
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/tasks/beautifier", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${VEETON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subtype: "clothing",
    inputs: {
      product_id: "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      background: "wood",
      angle_shot: "front",
      style: "ghost_mannequin"
    }
  }),
})

const data = await response.json()

Response · 202

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
  "type": "beautifier",
  "subtype": "clothing",
  "status": "queued",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "inputs": {
    "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "background": "wood",
    "angle_shot": "front",
    "style": "ghost_mannequin"
  },
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
    "mime_type": "image/jpeg",
    "width": 1,
    "height": 1,
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z",
    "created_at": "2026-04-27T14:32:00Z"
  },
  "quality_check": {
    "status": "not_checked",
    "checked_at": "2026-04-27T14:32:00Z",
    "findings": [
      {
        "kind": "garbled_text",
        "box": [
          1
        ]
      }
    ]
  },
  "failure_reason": {
    "code": "task_failed",
    "message": "string"
  },
  "started_at": "2026-04-27T14:32:00Z",
  "finished_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z"
}

Create an edit task

POST/v1/tasks/edit

Queues an edit of one image from a prompt ("Edit with AI" in the dashboard) and returns 202 immediately. The edit is a new image with its own id; the image you named never changes. Once completed, both are listed in GET /v1/images and exports, the edit naming its source in edited_from_image_id. Strongly recommended: send Idempotency-Key to make retries safe.

Parameters

inputsobjectrequired
Show child attributesHide child attributes
- image_idstringrequired
  The image to edit: the output of a beautifier or tryon task, or of a previous edit. Your own uploaded photos cannot be edited.
- promptstringrequired
  The change you want, in plain words.

Returns

Returns a Task object with status 202.

Errors

400
Invalid request
402
No active subscription / insufficient credits
404
Image not found
422
The image is not the output of a task, or its product is gone
500
Server error
502
Upstream queue unavailable

POST/v1/tasks/edit

curl https://api.veeton.com/v1/tasks/edit \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "image_id": "01HX5K2MZ7A3Q4FBNDC0EVDXIM",
    "prompt": "Remove the wrinkle on the left sleeve."
  }
}'
import requests

response = requests.post(
    "https://api.veeton.com/v1/tasks/edit",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    json={
          "inputs": {
            "image_id": "01HX5K2MZ7A3Q4FBNDC0EVDXIM",
            "prompt": "Remove the wrinkle on the left sleeve."
          }
        },
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/tasks/edit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${VEETON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: {
      image_id: "01HX5K2MZ7A3Q4FBNDC0EVDXIM",
      prompt: "Remove the wrinkle on the left sleeve."
    }
  }),
})

const data = await response.json()

Response · 202

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
  "type": "beautifier",
  "subtype": "clothing",
  "status": "queued",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "inputs": {
    "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "background": "wood",
    "angle_shot": "front",
    "style": "ghost_mannequin"
  },
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
    "mime_type": "image/jpeg",
    "width": 1,
    "height": 1,
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z",
    "created_at": "2026-04-27T14:32:00Z"
  },
  "quality_check": {
    "status": "not_checked",
    "checked_at": "2026-04-27T14:32:00Z",
    "findings": [
      {
        "kind": "garbled_text",
        "box": [
          1
        ]
      }
    ]
  },
  "failure_reason": {
    "code": "task_failed",
    "message": "string"
  },
  "started_at": "2026-04-27T14:32:00Z",
  "finished_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z"
}

Create tryon tasks

POST/v1/tasks/tryon

Composes a main garment + a model + an optional outfit into a rendered image, on the scene of your choice. Returns 202 immediately; the terminal state is delivered to your webhook(s) and GET /v1/tasks/{id} is available as a fallback. Strongly recommended: send Idempotency-Key to make retries safe.

Tryon has a single flow — no subtype to pass. The product's own type (garment / shoes / headwear) drives the worker.

Accepted slugs, with previews, are in the photo shoot catalog: Backgrounds, Angle shots and Models.

Parameters

inputsarray of objectsrequired
1..20 entries. Entries sharing the same model + main product + styling list are dispatched as a consistency group, so their outputs share identity/styling work and look consistent. Prefer one request with multiple entries over N separate calls when you want coherent variants.
Show child attributesHide child attributes
- product_idstringrequired
  The main garment to try on. Must be a Product owned by your organization.
- model_idstringrequired
  The model to wear the garment. Use GET /v1/models to discover available models. Org-generated models use ULIDs; Veeton-curated system models use shorter legacy ids (e.g. "19274"). Treat as opaque.
- outfit_product_idsarray of stringsoptional
  The outfit: up to 10 more of your products worn alongside the main one (main = top, outfit = pants + shoes) — "Outfits" in the dashboard. Cannot include the main product_id.
- backgroundstringrequired
  Slug from the tryon backgrounds catalogue (https://api.veeton.com/reference/catalogues/tryon/backgrounds) — a superset of beautifier that adds indoor / outdoor scenes and excludes floor. Hex slugs include the leading #.
- angle_shotstringrequired
  Slug from the tryon angle-shots catalogue (https://api.veeton.com/reference/catalogues/tryon/angle-shots). Your org's custom angle shots are also accepted.
- gazeenumoptional
  - auto
  - camera
  - away
- aspect_ratioenumoptional
  Possible enum values (9)
  - auto
  - 1/1
  - 2/3
  - 3/4
  - 4/5
  - 9/16
  - 3/2
  - 4/3
  - 16/9

Returns

Returns a TaskBatchResponse object with status 202.

Errors

400
One or more inputs failed validation. The response lists every bad input via TryonErrorEnvelope so callers do not have to retry-and-bisect.
402
No active subscription / insufficient credits
500
Internal error while creating tasks (validated inputs but RPC or reload failed)

POST/v1/tasks/tryon

curl https://api.veeton.com/v1/tasks/tryon \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [
    {
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "model_id": "01HX5K2MZ7A3Q4FBNDC0EVDXMD1",
      "outfit_product_ids": [
        "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
      ],
      "background": "park",
      "angle_shot": "full_body_relaxed_symmetric",
      "gaze": "auto",
      "aspect_ratio": "auto"
    }
  ]
}'
import requests

response = requests.post(
    "https://api.veeton.com/v1/tasks/tryon",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    json={
          "inputs": [
            {
              "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
              "model_id": "01HX5K2MZ7A3Q4FBNDC0EVDXMD1",
              "outfit_product_ids": [
                "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
              ],
              "background": "park",
              "angle_shot": "full_body_relaxed_symmetric",
              "gaze": "auto",
              "aspect_ratio": "auto"
            }
          ]
        },
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/tasks/tryon", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${VEETON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [
      {
        product_id: "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
        model_id: "01HX5K2MZ7A3Q4FBNDC0EVDXMD1",
        outfit_product_ids: [
          "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
        ],
        background: "park",
        angle_shot: "full_body_relaxed_symmetric",
        gaze: "auto",
        aspect_ratio: "auto"
      }
    ]
  }),
})

const data = await response.json()

Response · 202

{
  "data": [
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
      "type": "beautifier",
      "subtype": "clothing",
      "status": "queued",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "inputs": {
        "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
        "background": "wood",
        "angle_shot": "front",
        "style": "ghost_mannequin"
      },
      "output_image": {
        "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
        "mime_type": "image/jpeg",
        "width": 1,
        "height": 1,
        "url": "https://example.com/…",
        "url_expires_at": "2026-04-27T14:32:00Z",
        "created_at": "2026-04-27T14:32:00Z"
      },
      "quality_check": {
        "status": "not_checked",
        "checked_at": "2026-04-27T14:32:00Z",
        "findings": [
          {
            "kind": "garbled_text",
            "box": []
          }
        ]
      },
      "failure_reason": {
        "code": "task_failed",
        "message": "string"
      },
      "started_at": "2026-04-27T14:32:00Z",
      "finished_at": "2026-04-27T14:32:00Z",
      "created_at": "2026-04-27T14:32:00Z"
    }
  ]
}

Retrieve a task

GET/v1/tasks/{task_id}

Available as a fallback to webhook delivery — useful for replay and recovery.

Parameters

task_idstringrequired
Crockford-base32 ULID (26 chars).

Returns

Returns a Task object with status 200.

Errors

404
Not found

GET/v1/tasks/{task_id}

curl https://api.veeton.com/v1/tasks/01HX5K2MZ7A3Q4FBNDC0EVDXY1 \
  -H "Authorization: Bearer $VEETON_KEY"
import requests

response = requests.get(
    "https://api.veeton.com/v1/tasks/01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/tasks/01HX5K2MZ7A3Q4FBNDC0EVDXY1", {
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
})

const data = await response.json()

Response · 200

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
  "type": "beautifier",
  "subtype": "clothing",
  "status": "queued",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "inputs": {
    "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "background": "wood",
    "angle_shot": "front",
    "style": "ghost_mannequin"
  },
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
    "mime_type": "image/jpeg",
    "width": 1,
    "height": 1,
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z",
    "created_at": "2026-04-27T14:32:00Z"
  },
  "quality_check": {
    "status": "not_checked",
    "checked_at": "2026-04-27T14:32:00Z",
    "findings": [
      {
        "kind": "garbled_text",
        "box": [
          1
        ]
      }
    ]
  },
  "failure_reason": {
    "code": "task_failed",
    "message": "string"
  },
  "started_at": "2026-04-27T14:32:00Z",
  "finished_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z"
}