Types d’assets
| Type | Description | Stocké en base |
|---|---|---|
face | Images de référence du visage pour les personnes | Oui |
template | Templates de référence de style | Oui |
bucket | Import 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ètre | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
type | string | Non | - | Filtre par type : face, template, bucket |
page | number | Non | 1 | Numéro de page |
limit | number | Non | 20 | É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)
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
file | File | Oui | Fichier image (le type MIME doit commencer par image/) |
type | string | Oui | face, template ou bucket |
description | string | Non | Description |
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)
| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
base64 | string | Oui | - | Image encodée en base64 (avec ou sans préfixe data:) |
type | string | Oui | - | face, template ou bucket |
filename | string | Non | généré automatiquement | Nom du fichier |
mimeType | string | Non | image/jpeg | image/jpeg, image/png, image/webp, image/gif |
description | string | Non | - | 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ètre | Type | Description |
|---|---|---|
id | string (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ètre | Type | Description |
|---|---|---|
id | string (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 renvoieisError: true pour les erreurs. Ces opérations de gestion ne consomment aucun crédit.
| REST | MCP | Paramètres / effet |
|---|---|---|
PATCH /api/persons/:id | update_person | name? (1–100), description? (max 500) ; null efface la description ; au moins un champ |
DELETE /api/persons/:id | delete_person | Supprime le profil et ses associations ; conserve les images stockées |
DELETE /api/persons/:id/images/:imageId | remove_person_image | Détache cette association existante, sans supprimer l'asset |
PUT /api/persons/:id/default | set_default_person | Défaut de l'organisation, idempotent ; conserve les permissions de propriété |
GET /api/assets/:id | get_asset | UUID d'un asset stocké autorisé |
GET /api/templates/:id | get_template | Template du catalogue publié ou privé créé par vous |
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}'