Référence API

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}

L'objet Task

Attributs

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.
Afficher les attributs enfantsMasquer les attributs enfants
- 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
Afficher les attributs enfantsMasquer les attributs enfants
- 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
Afficher les attributs enfantsMasquer les attributs enfants
- 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
  Afficher les attributs enfantsMasquer les attributs enfants
  - 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
Afficher les attributs enfantsMasquer les attributs enfants
- 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.

L'objet Task

{
  "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.

Paramètres

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

Retour

Retourne un objet TaskList avec le statut 200.

Erreurs

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()

Réponse · 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.

Paramètres

subtypeenum, nullablerequis
- clothing
- shoes
- headwear
- glasses
- bags
inputsobjectrequis
Afficher les attributs enfantsMasquer les attributs enfants
- product_idstringrequis
  Crockford-base32 ULID (26 chars).
- backgroundstringrequis
  Slug from the beautifier backgrounds catalogue (https://api.veeton.com/reference/catalogues/beautifier/backgrounds). Hex-coded slugs include the leading # (e.g. "#ffffff").
- angle_shotstringrequis
  Allowed values depend on subtype; see the beautifier angle-shots catalogue (https://api.veeton.com/reference/catalogues/beautifier/angle-shots).
- styleenumoptionnel
  - ghost_mannequin
  - flatlay

Retour

Retourne un objet Task avec le statut 202.

Erreurs

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()

Réponse · 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.

Paramètres

inputsobjectrequis
Afficher les attributs enfantsMasquer les attributs enfants
- image_idstringrequis
  The image to edit: the output of a beautifier or tryon task, or of a previous edit. Your own uploaded photos cannot be edited.
- promptstringrequis
  The change you want, in plain words.

Retour

Retourne un objet Task avec le statut 202.

Erreurs

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()

Réponse · 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.

Paramètres

inputsarray of objectsrequis
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.
Afficher les attributs enfantsMasquer les attributs enfants
- product_idstringrequis
  The main garment to try on. Must be a Product owned by your organization.
- model_idstringrequis
  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 stringsoptionnel
  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.
- backgroundstringrequis
  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_shotstringrequis
  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.
- gazeenumoptionnel
  - auto
  - camera
  - away
- aspect_ratioenumoptionnel
  Valeurs possibles (9)
  - auto
  - 1/1
  - 2/3
  - 3/4
  - 4/5
  - 9/16
  - 3/2
  - 4/3
  - 16/9

Retour

Retourne un objet TaskBatchResponse avec le statut 202.

Erreurs

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()

Réponse · 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.

Paramètres

task_idstringrequis
Crockford-base32 ULID (26 chars).

Retour

Retourne un objet Task avec le statut 200.

Erreurs

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()

Réponse · 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"
}