API reference

Tasks

An image-generation job. Two families share one shape: beautifier renders the product alone on a background, tryon 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/tryon
GET/v1/tasks/{task_id}

The Task object

Attributes

idstring
Crockford-base32 ULID (26 chars).
typeenum
- beautifier
- tryon
subtypeenum, nullable
- clothing
- shoes
- headwear
statusenum
- queued
- running
- succeeded
- failed
product_idstring
Crockford-base32 ULID (26 chars).
output_imageobject, nullable
Show child attributesHide child attributes
- idstring
  Crockford-base32 ULID (26 chars).
- urlstring (URL)
- url_expires_attimestamp
  RFC 3339 / ISO 8601 timestamp.
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",
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z"
  },
  "failure_reason": {
    "code": "model_unsafe_content",
    "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 (both beautifier and tryon). 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, running, succeeded, failed.
type — beautifier or tryon.
subtype — clothing, shoes, headwear. Implicitly narrows to beautifier (tryon has no subtype).
product_id — only tasks referencing this product.

Parameters

limitinteger· queryoptional
Default: 25
cursorstring· queryoptional
statusenum· queryoptional
- queued
- running
- succeeded
- failed
typeenum· queryoptional
- beautifier
- tryon
subtypeenum, nullable· queryoptional
- clothing
- shoes
- headwear
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",
      "output_image": {
        "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
        "url": "https://example.com/…",
        "url_expires_at": "2026-04-27T14:32:00Z"
      },
      "failure_reason": {
        "code": "model_unsafe_content",
        "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 (succeeded / 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, or headwear); each has its own input rules, see https://api.veeton.com/guides/tasks.

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

Parameters

subtypeenum, nullablerequired
- clothing
- shoes
- headwear
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
  - 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"
  }
}'
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"
          }
        },
)

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"
    }
  }),
})

const data = await response.json()

Response · 202

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
  "type": "beautifier",
  "subtype": "clothing",
  "status": "queued",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z"
  },
  "failure_reason": {
    "code": "model_unsafe_content",
    "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 + optional stylings 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 tryon catalogue: 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.
- styling_product_idsarray of stringsoptional
  Optional additional garments composed onto the same model alongside the main product (e.g. main = top, styling = pants + shoes). 0–10 items. 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.
- look_at_camerabooleanoptional
  When true (default) the model looks at the camera. When false the model looks away.
  Default: true

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",
      "styling_product_ids": [
        "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
      ],
      "background": "park",
      "angle_shot": "full_body_relaxed_symmetric",
      "look_at_camera": true
    }
  ]
}'
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",
              "styling_product_ids": [
                "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
              ],
              "background": "park",
              "angle_shot": "full_body_relaxed_symmetric",
              "look_at_camera": True
            }
          ]
        },
)

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",
        styling_product_ids: [
          "01HX5K2MZ7A3Q4FBNDC0EVDXY2"
        ],
        background: "park",
        angle_shot: "full_body_relaxed_symmetric",
        look_at_camera: true
      }
    ]
  }),
})

const data = await response.json()

Response · 202

{
  "tasks": [
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
      "type": "beautifier",
      "subtype": "clothing",
      "status": "queued",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "output_image": {
        "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
        "url": "https://example.com/…",
        "url_expires_at": "2026-04-27T14:32:00Z"
      },
      "failure_reason": {
        "code": "model_unsafe_content",
        "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",
  "output_image": {
    "id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    "url": "https://example.com/…",
    "url_expires_at": "2026-04-27T14:32:00Z"
  },
  "failure_reason": {
    "code": "model_unsafe_content",
    "message": "string"
  },
  "started_at": "2026-04-27T14:32:00Z",
  "finished_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z"
}