Référence API

Images

Every image we hold: your photos, uploaded as bytes, and the renders made from them. Addressed by id, typed by content, and every URL you get back is a short-lived signed one. The list is the catalog read a PIM or DAM sync wants.

Endpoints

POST/v1/images
GET/v1/images
GET/v1/images/{image_id}

L'objet Image

Attributs

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.

L'objet 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"
}

L'objet ImageListItem

An image as GET /v1/images lists it: the Image object plus what it is and where it belongs. Also the line format of a JSONL export manifest.

Attributs

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.
product_idstring
The product this image belongs to — the one it was made for. A tryon styled with other products lists those in also_features.
roleenum
- source
- beautifier
- tryon
- recoloring
ai_generatedboolean
False only for your own photos (role: source). Provided for EU AI Act labelling obligations.
task_idstring, nullable
The task that produced it, for GET /v1/tasks/{id}. Null for your photos and for generations made in the dashboard.
attributesmap
Per-role facts, flat and open: orientation (source, and recoloring: the view it was made from), angle_shot, background, model_id (tryon), hex_color and, for a several-colour result, hex_colors (recoloring), edit_number (edits). Ignore keys you do not know; new ones appear without a version bump.
edited_from_image_idstring, nullable
For an edit made through POST /v1/tasks/edit: the image it was made from. Null otherwise. Every version is listed as its own image, so an image nothing was edited from is the end of a chain.
archivedboolean
True when this result, or the result this edit was made from, is archived in the dashboard. Archived results are left out of ZIP exports.
also_featuresarray of strings
Other products visible in this image (a tryon's outfit). The image is listed once, under the product it was made for; fan it out to these pages if your merchandising wants it there too.
suggested_filenamestring
A filename (never a path) built from your export naming template, with the real extension of the bytes.

L'objet ImageListItem

{
  "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",
  "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "role": "source",
  "ai_generated": true,
  "task_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "attributes": {
    "orientation": "front"
  },
  "edited_from_image_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
  "archived": true,
  "also_features": [
    "01HX5K2MZ7A3Q4FBNDC0EVDXY1"
  ],
  "suggested_filename": "TEE-SAGE-001_front_cleaned.webp"
}

Upload an image

POST/v1/images

Single-shot upload via multipart/form-data. The bytes flow through this endpoint to Supabase Storage, and the image is only reported as created once they are on disk — so the returned id is immediately referenceable from POST /v1/products. If any step fails the upload is rolled back whole; a partially-stored image is never returned.

This is the single-product path, paired with POST /v1/products. For a catalogue, skip the upload entirely: POST /v1/imports takes each photo as an https:// URL and fetches it for you.

Limits: body must be ≤ 10 MB. Accepted formats: JPEG, PNG, WebP — detected from the file's bytes; the multipart Content-Type you declare is ignored.

Form fields:

file (required): the image bytes.

Example:

curl -X POST https://api.veeton.com/v1/images \
  -H "Authorization: Bearer ak_..." \
  -F "file=@./crewneck-front.jpg"

Paramètres

filestringrequis
Les octets de l'image, dans un champ multipart/form-data. JPEG, PNG ou WebP, jusqu'à 10 Mo ; le type est lu depuis les octets.

Retour

Retourne un objet Image avec le statut 201.

Erreurs

400
Invalid request
413
Payload too large
415
Unsupported media type
500
Server error

POST/v1/images

curl https://api.veeton.com/v1/images \
  -H "Authorization: Bearer $VEETON_KEY" \
  -F "file=@./photo.jpg"
import requests

response = requests.post(
    "https://api.veeton.com/v1/images",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    files={"file": open("photo.jpg", "rb")},
)

print(response.json())
const form = new FormData()
form.append("file", new Blob([await readFile("./photo.jpg")]), "photo.jpg")

const response = await fetch("https://api.veeton.com/v1/images", {
  method: "POST",
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
  body: form,
})

const data = await response.json()

Réponse · 201

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

List images

GET/v1/images

Every image we hold for your products — your own photos, beautifier renders, tryons and their edits — each with a signed URL, what it is (role, attributes) and where it belongs (product_id, also_features). This is the read a PIM or DAM sync wants; suggested_filename and ai_generated are there for filing and labelling.

Each image appears exactly once, under the product it was made for. A tryon of a top styled with pants lives on the top; the pants are listed in also_features, and whether it also goes on the pants page is your merchandising call, not our data model.

Pages are cut on product boundaries: a page holds every image of up to limit products, newest product first, so the count of images per page varies. Narrow with product_id or role; since= returns only the images of products that changed (pair it with GET /v1/products?since= for deletions).

Every version made through the API is its own image with its own id: a task's output, and each edit, which names its source in edited_from_image_id. A crop or retouch made in the dashboard is not listed. To freeze a selection into a file instead of paging, use POST /v1/exports.

Paramètres

limitinteger· queryoptionnel
Par défaut : 25
cursorstring· queryoptionnel
product_idstring· queryoptionnel
Only the images of this product.
rolestring· queryoptionnel
Comma-separated ImageRole values.
sincetimestamp· queryoptionnel
Delta mode: only the images of products that changed at or after this instant (a photo attached or removed, a generation or edit completed, a result archived or deleted, a field edited). Each product comes back whole, so replace its images with these rows; a product left with no images has none here. Pair with GET /v1/products?since= for deletions.

Retour

Retourne un objet ImageList avec le statut 200.

Erreurs

400
Invalid cursor or role
500
Server error

GET/v1/images

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

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

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

const data = await response.json()

Réponse · 200

{
  "data": [
    {
      "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",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "role": "source",
      "ai_generated": true,
      "task_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "attributes": {
        "orientation": "front"
      },
      "edited_from_image_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "archived": true,
      "also_features": [
        "01HX5K2MZ7A3Q4FBNDC0EVDXY1"
      ],
      "suggested_filename": "TEE-SAGE-001_front_cleaned.webp"
    }
  ],
  "next_cursor": "eyJpZCI6InByb2RfMDFIWCJ9",
  "has_more": true
}

Retrieve an image

GET/v1/images/{image_id}

Returns the image metadata and a short-lived signed URL pointing at the original bytes. Useful for re-fetching expired URLs or inspecting reference images attached to a Product. The URL TTL is one hour — re-fetch on expiry, do not cache.

Paramètres

image_idstringrequis
Crockford-base32 ULID (26 chars).

Retour

Retourne un objet Image avec le statut 200.

Erreurs

404
Not found
500
Server error

GET/v1/images/{image_id}

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

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

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

const data = await response.json()

Réponse · 200

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