Synchroniser et exporter

Lisez chaque visuel que nous détenons, rattaché à son produit. Demandez ce qui a changé depuis votre dernière exécution, suppressions comprises, ou figez une sélection dans un fichier.

Une synchronisation PIM ou DAM, ce sont deux lectures, les produits et les images, chacune avec son delta. Ce n’est délibérément pas une liste de fichiers : chaque image porte l’identifiant du produit auquel elle appartient, si bien que votre côté n’a jamais à analyser des noms de fichiers pour déterminer à quel produit appartient un rendu.

for product in GET /v1/products?since=T:  upsert, ou suppression si deleted_at est renseigné
pour chaque produit modifié :              remplacez ses images par celles de GET /v1/images?since=T

Lire les images

GET/v1/images

Toutes les images que nous détenons pour vos produits : vos propres photos, les rendus de l’Embellisseur produit, les shootings photo et leurs retouches. Du produit le plus récent au plus ancien.

{
  "data": [
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYS",
      "mime_type": "image/jpeg",
      "width": 2000, "height": 2667,
      "url": "https://…signed…",
      "url_expires_at": "2026-09-03T15:32:00Z",
      "created_at": "2026-09-01T09:12:44Z",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "role": "source",
      "ai_generated": false,
      "task_id": null,
      "attributes": { "orientation": "front" },
      "also_features": [],
      "suggested_filename": "TEE-SAGE-001_front.jpg"
    },
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXZ9",
      "mime_type": "image/webp",
      "width": 1536, "height": 2048,
      "url": "https://…signed…",
      "url_expires_at": "2026-09-03T15:32:00Z",
      "created_at": "2026-09-02T16:40:03Z",
      "product_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY1",
      "role": "tryon",
      "ai_generated": true,
      "task_id": "01HX5K2MZ7A3Q4FBNDC0EVDXY2",
      "attributes": { "angle_shot": "full_body_relaxed_symmetric", "background": "park", "model_id": "01HX5K2MZ7A3Q4FBNDC0EVDXMD1" },
      "also_features": ["01HX5K2MZ7A3Q4FBNDC0EVDXPN"],
      "suggested_filename": "TEE-SAGE-001_tryon_park.webp"
    }
  ],
  "next_cursor": "eyJpZCI6InByb2RfMDFIWCJ9",
  "has_more": true
}

Ce qu’un élément vous indique

Champ	À utiliser pour
`id`, `mime_type`, `width`, `height`, `url`, `url_expires_at`, `created_at`	Le même objet `Image` que renvoie chaque endpoint. `url` pointe vers cette image précise et reste valide une heure. Un recadrage ou une retouche faits dans le tableau de bord n’ont pas d’identifiant public et ne sont pas listés. Une URL expirée se récupère à nouveau avec `GET /v1/images/{id}`, jamais en relistant.
`product_id`	Le produit auquel cette image appartient, celui pour lequel elle a été réalisée.
`role`	La nature de l’image : `source` (votre photo), `beautifier`, `tryon`, `recoloring`. Les retouches conservent le rôle de la génération dont elles proviennent ; `attributes.edit_number` indique laquelle. De nouveaux rôles peuvent apparaître ; traitez les valeurs inconnues comme opaques.
`ai_generated`	`false` uniquement pour vos propres photos (`role: source`). Pour l’étiquetage exigé par l’AI Act européen.
`task_id`	La tâche qui l’a produite, pour `GET /v1/tasks/{id}`. Null pour vos photos et pour les générations réalisées dans le tableau de bord.
`edited_from_image_id`	Pour une retouche : l’image dont elle provient. Null sinon. Chaque version est une ligne à part, donc une image dont rien n’a été retouché est la fin d’une chaîne.
`archived`	`true` quand le résultat a été archivé dans le tableau de bord. Les résultats archivés sont exclus des exports ZIP.
`attributes`	Des faits à plat, ouverts, propres à chaque rôle : `orientation`, `angle_shot`, `background`, `model_id`, `edit_number` ; un `recoloring` porte l’`orientation` de la vue d’origine et son `hex_color` (plus `hex_colors` s’il en a plusieurs). Ignorez les clés que vous ne connaissez pas.
`also_features`	Les autres produits visibles dans cette image (les pièces de stylisme d’un shooting photo `tryon`).
`suggested_filename`	Un nom de fichier, jamais un chemin, construit à partir du modèle de nommage d’export de votre organisation avec l’extension réelle des octets.

Chaque image apparaît exactement une fois, sous le produit pour lequel elle a été réalisée. Un shooting photo (tryon) d’un haut stylisé avec un pantalon est rattaché au haut ; le pantalon est listé dans also_features. Le faire figurer aussi sur la page du pantalon relève de votre choix de merchandising.

Filtres et pagination

product_id=… liste les images d’un seul produit.
role=beautifier,tryon ne conserve que ces rôles.
limit (de 1 à 100, 25 par défaut) et cursor paginent. Les pages sont coupées entre produits : une page contient toutes les images d’au plus limit produits, si bien que le nombre d’images par page varie.

Uniquement ce qui a changé

Ajoutez since=<timestamp> à l’une ou l’autre liste et vous n’obtenez que ce qui a changé à cet instant ou après.

curl "https://api.veeton.com/v1/products?since=2026-09-02T00:00:00Z" \
  -H "Authorization: Bearer $VEETON_KEY"
curl "https://api.veeton.com/v1/images?since=2026-09-02T00:00:00Z" \
  -H "Authorization: Bearer $VEETON_KEY"

GET /v1/products?since= renvoie les produits modifiés : un champ modifié, une photo attachée ou retirée, une génération ou une retouche terminée, un résultat archivé ou supprimé, ou le produit supprimé. Chacun est son état actuel complet, donc faites-en un upsert en entier. Un produit supprimé apparaît une fois avec deleted_at renseigné et un tableau images vide : supprimez-le de votre côté.
GET /v1/images?since= renvoie toutes les images de ces mêmes produits, si bien que les images d’un produit modifié sont toujours relues ensemble. Remplacez les images de ce produit par ces lignes : c’est ainsi que vous apprenez qu’une image a été retirée. Un produit qui n’a plus d’image n’a aucune ligne, prenez donc la liste des produits modifiés dans GET /v1/products?since=.

Utilisez le created_at de votre exécution précédente, moins une marge de sécurité, comme prochain since. Un job nocturne devient alors un delta, et non une relecture complète.

Figer une sélection dans un fichier

POST/v1/exports

Les mêmes éléments image sous forme d’artefact stable : un manifeste JSONL (un élément par ligne) ou un ZIP des fichiers image rendus par le même pipeline d’export que celui du tableau de bord, avec le modèle de nommage de votre organisation et les formats propres à chaque workflow.

curl https://api.veeton.com/v1/exports \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"format":"zip","product_ids":["01HX5K2MZ7A3Q4FBNDC0EVDXY1"],"role":["beautifier","tryon"]}'

Sélectionnez jusqu’à 500 produits avec product_ids, ou omettez-le pour l’ensemble du catalogue visible par l’API (même plafond). Affinez avec role.
format: manifest (par défaut) est écrit immédiatement ; la réponse est déjà completed avec une url signée.
format: zip est rendu de manière asynchrone. Interrogez GET /v1/exports/{id}, qui porte Retry-After tant qu’il est en queued ou processing, ou abonnez-vous à export.completed et export.failed.

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXEX",
  "format": "zip",
  "status": "queued",
  "url": null,
  "url_expires_at": null,
  "expires_at": null,
  "total_images": 148,
  "error": null,
  "created_at": "2026-09-03T14:30:09Z",
  "started_at": null,
  "finished_at": null
}

Les URL d’images contenues dans un manifeste sont valides une heure après son écriture ; les identifiants d’images sont permanents. L’URL de l’artefact sur le job est re-signée à chaque lecture : mettez le fichier en cache, pas l’URL.

Un ZIP est conservé 48 heures après sa production. Le job porte l’échéance dans expires_at ; passé ce délai, le job reste completed, url vaut null, et un nouvel export vous redonne les fichiers. Les manifestes n’expirent pas (expires_at vaut null).

GET/v1/exports liste vos jobs d’export, du plus récent au plus ancien, avec un filtre status. Les imports disposent de la même liste sur GET /v1/imports.