API Assets

L’API Assets te permet d’importer et de gérer les images utilisées dans YouThumbAI. Les assets sont la base des profils de visage et des templates personnalisés.

Types d’assets

TypeDescriptionStocké en base
faceImages de référence du visage pour les personnesOui
templateTemplates de référence de styleOui
bucketImport de fichier temporaire (sans entrée en base)Non
Le type bucket importe les fichiers dans un stockage temporaire sans créer d’entrée en base de données. Pratique pour les images éphémères nécessaires pendant un workflow de génération.

Lister les assets

Liste vos images stockées ou partagées avec l’organisation, y compris les imports non publiés.
GET /api/assets

Paramètres de requête

ParamètreTypeObligatoireDéfautDescription
typestringNon-Filtre par type : face, template, bucket
pagenumberNon1Numéro de page
limitnumberNon20Éléments par page (100 max)
bash
# Lister tous les assets
curl https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key"

# Lister uniquement les assets de visage
curl "https://youthumb.ai/api/assets?type=face" \
  -H "x-api-key: your_api_key"

# Paginé
curl "https://youthumb.ai/api/assets?page=2&limit=10" \
  -H "x-api-key: your_api_key"

Réponse de la liste

json
{
  "success": true,
  "data": {
    "assets": [
      {
        "id": "asset-uuid",
        "type": "face",
        "url": "https://...",
        "name": "photo.jpg",
        "description": "Front face photo",
        "mimeType": "image/jpeg",
        "size": 245000,
        "width": 1920,
        "height": 1080,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20
    }
  }
}

Importer un asset

Importe une image. Deux modes sont pris en charge : multipart/form-data et JSON (base64).
POST /api/assets

Mode 1 : multipart (FormData)

ChampTypeObligatoireDescription
fileFileOuiFichier image (le type MIME doit commencer par image/)
typestringOuiface, template ou bucket
descriptionstringNonDescription
bash
curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -F "file=@face-photo.jpg" \
  -F "type=face" \
  -F "description=Front face photo"

Mode 2 : base64 (JSON)

ChampTypeObligatoireDéfautDescription
base64stringOui-Image encodée en base64 (avec ou sans préfixe data:)
typestringOui-face, template ou bucket
filenamestringNongénéré automatiquementNom du fichier
mimeTypestringNonimage/jpegimage/jpeg, image/png, image/webp, image/gif
descriptionstringNon-Description (500 caractères max)
bash
curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "type": "face",
    "filename": "my-face.jpg",
    "mimeType": "image/jpeg",
    "description": "Front face photo"
  }'

Réponse de l’import

json
{
  "success": true,
  "data": {
    "id": "new-asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "my-face.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
Pour les imports bucket, la réponse contient un id vide et null pour width/height, car le fichier est stocké temporairement sans enregistrement en base de données.

Obtenir un asset

Récupère un asset précis par son ID.
GET /api/assets/{id}
ParamètreTypeDescription
idstring (UUID)ID de l’asset
bash
curl https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Réponse

json
{
  "success": true,
  "data": {
    "id": "asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "photo.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Supprimer un asset

Supprime un asset par son ID.
DELETE /api/assets/{id}
ParamètreTypeDescription
idstring (UUID)ID de l’asset
bash
curl -X DELETE https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Réponse de suppression

json
{
  "success": true,
  "data": {
    "message": "Asset deleted"
  }
}

Exemple complet : JavaScript

javascript
const API = 'https://youthumb.ai/api';
const headers = {
  'x-api-key': process.env.YOUTHUMB_API_KEY,
  'Content-Type': 'application/json',
};

// Importer une image de visage (base64)
async function uploadFaceImage(base64Data, filename) {
  const response = await fetch(`${API}/assets`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      base64: base64Data,
      type: 'face',
      filename,
      mimeType: 'image/jpeg',
    }),
  });
  return response.json();
}

// Lister tous les assets de visage
async function listFaceAssets() {
  const response = await fetch(`${API}/assets?type=face`, { headers });
  return response.json();
}

// Importer les visages puis créer la personne
async function setupPerson(name, faceImages) {
  // 1. Importer toutes les images de visage
  const uploadResults = await Promise.all(
    faceImages.map((img) => uploadFaceImage(img.base64, img.filename))
  );

  const imageIds = uploadResults.map((r) => r.data.id);

  // 2. Créer la personne avec les images importées
  const person = await fetch(`${API}/persons`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ name, imageIds }),
  });

  return person.json();
}
Les assets sont le prérequis de l’API Persons. Importe d’abord les images de visage comme assets, puis passe leurs ID lors de la création ou de la mise à jour d’une personne.

Ressources : personnes, imports et catalogue

Toutes les opérations utilisent l'identité connectée. Un asset stocké doit appartenir à l'organisation sélectionnée et être le vôtre ou partagé avec elle. Les imports restent non publiés et sont retrouvables. Un ID absent ou inaccessible renvoie 404 ; un refus de permission 403 ; une entrée invalide 400. Le MCP renvoie isError: true pour les erreurs. Ces opérations de gestion ne consomment aucun crédit.
RESTMCPParamètres / effet
PATCH /api/persons/:idupdate_personname? (1–100), description? (max 500) ; null efface la description ; au moins un champ
DELETE /api/persons/:iddelete_personSupprime le profil et ses associations ; conserve les images stockées
DELETE /api/persons/:id/images/:imageIdremove_person_imageDétache cette association existante, sans supprimer l'asset
PUT /api/persons/:id/defaultset_default_personDéfaut de l'organisation, idempotent ; conserve les permissions de propriété
GET /api/assets/:idget_assetUUID d'un asset stocké autorisé
GET /api/templates/:idget_templateTemplate du catalogue publié ou privé créé par vous
Les mutations MCP demandent mcp:assets et le droit Images et personnes actif. Les lectures demandent mcp:read et Lecture actif. Les paramètres MCP sont personId, imageId, assetId ou templateId à la place des segments de chemin. Lecture/modification d'une personne renvoie son profil avec images et imageCount ; suppression renvoie {"deleted":true}. Création et ajout de photos vérifient aussi chaque image avant toute écriture.

Retrouver les imports

GET /api/assets / list_assets accepte type (face, template, bucket), search, isPublished, page (1 par défaut), limit (20, max 100). Sans type, liste les images face/template stockées. Recherche sur nom/description ; visibilité et filtres appliqués avant pagination et comptage. Chaque asset stocké porte isPublished, ownerScope: "organization". Pagination : page, limit, total, totalPages, hasMore. type=bucket liste le dossier temporaire personnel de l'appelant, commun à ses organisations. Chaque résultat porte ownerScope: "user", id: "", fileKey stable, url et isFavorite. Utiliser contentImages: [{"url": "URL_RENVOYÉE"}] pour générer ; get_asset et userImageId exigent un UUID d'asset persisté, jamais une clé bucket. favorite=true sélectionne les favoris, favorite=false les exclut ; sans filtre, les deux sont inclus. search recherche les noms de fichier. Réservés au bucket, sortBy=name|createdAt et sortOrder=asc|desc valent par défaut createdAt descendant. Les dates absentes ou invalides restent createdAt: null et sont placées en fin dans les deux sens ; les égalités sont départagées par fileKey ascendant. Ces trois filtres bucket sont refusés pour les autres types ; isPublished est invalide pour le bucket. Le service parcourt tous les fichiers correspondants par lots de 100, déduplique les chemins et exclut les non-images/marqueurs avant filtrage des favoris, tri et pagination publique. total compte les images filtrées, totalPages = ceil(total / limit) et hasMore indique une page suivante. Une liste vide a des totaux de 0 ; une page hors borne est vide. Les favoris orphelins ne créent aucun asset. Chaque requête énumère le dossier correspondant : un gros dossier demande davantage d'appels stockage ; les changements concurrents ne constituent pas un snapshot atomique. Toute erreur d'une page fournisseur fait échouer la requête, sans succès partiel. Pas de suppression temporaire par /api/assets/:id. Exemple : GET /api/assets?type=bucket&search=logo&favorite=true&sortBy=createdAt&sortOrder=desc&page=1&limit=20 ou MCP list_assets({"type":"bucket","search":"logo","favorite":true,"sortBy":"createdAt","sortOrder":"desc","page":1,"limit":20}).

Trois espaces d'identifiants

GET /api/templates / list_templates recherche titre, description et tags du catalogue via search. scope=public (défaut) liste les templates publiés ; scope=mine seulement vos créations, publiées ou privées. isPublished=false exige scope=mine. category, isFeatured, page, limit restent disponibles. Réponse : templates et pagination (page, limit, total, totalPages). Un UUID du catalogue va dans templateId. Une référence importée se retrouve avec list_assets(type="template") : son URL va dans styleReferenceUrl, son UUID dans un userImageId de contenu ou un assetId d'aide au prompt. Un fichier temporaire utilise son URL. Ne pas mélanger IDs de catalogue, IDs d'assets et clés de fichiers.
bash
curl "$BASE/api/assets?type=template&search=studio&page=1&limit=20" -H "x-api-key: $YOUTHUMB_API_KEY"
curl "$BASE/api/templates?scope=mine&isPublished=false&search=studio" -H "x-api-key: $YOUTHUMB_API_KEY"
curl -X PATCH "$BASE/api/persons/$PERSON_ID" -H "x-api-key: $YOUTHUMB_API_KEY" -H "Content-Type: application/json" -d '{"description":null}'