Principe
Dans YouThumbAI, une personne :- est un profil nommé associé à ton organisation
- contient une ou plusieurs images de référence du visage
- sert à l’IA pour générer des face swaps cohérents
- peut être référencée par ID ou par nom lors de la création de miniatures
Pour de meilleurs résultats, importe 3 à 5 images nettes du visage sous différents angles. Consulte le guide d’optimisation du profil de visage pour des conseils détaillés.
Lister les personnes
Récupère toutes les personnes de ton organisation.GET /api/persons
bash
curl https://youthumb.ai/api/persons \
-H "x-api-key: your_api_key"json
{
"success": true,
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Creator",
"description": "Main channel host",
"imageCount": 5,
"createdAt": "2024-01-10T08:00:00.000Z"
},
{
"id": "987fcdeb-51a2-43e8-b789-426614174111",
"name": "Guest Sarah",
"description": "Co-host for tech reviews",
"imageCount": 3,
"createdAt": "2024-01-12T14:30:00.000Z"
}
]
}Créer une personne
Crée un nouveau profil de personne.POST /api/persons
Corps de la requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
name | string | Oui | Nom de la personne (1-100 caractères) |
description | string | Non | Description (500 caractères max) |
imageIds | array | Non | Tableau d’ID d’assets importés à rattacher |
bash
curl -X POST https://youthumb.ai/api/persons \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alex YouTuber",
"description": "Main channel presenter - tech and gaming content"
}'bash
curl -X POST https://youthumb.ai/api/persons \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alex YouTuber",
"description": "Main channel presenter",
"imageIds": [
"img-123-uuid",
"img-456-uuid",
"img-789-uuid"
]
}'Réponse de création
json
{
"success": true,
"data": {
"id": "new-person-uuid",
"name": "Alex YouTuber",
"description": "Main channel presenter - tech and gaming content",
"imageCount": 0,
"createdAt": "2024-01-15T10:00:00.000Z"
}
}Obtenir le détail d’une personne
Récupère le détail d’une personne précise.GET /api/persons/{id}
| Paramètre | Type | Description |
|---|---|---|
id | string (UUID) | ID de la personne |
bash
curl https://youthumb.ai/api/persons/123e4567-e89b-12d3-a456-426614174000 \
-H "x-api-key: your_api_key"Réponse avec le détail de la personne
json
{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Creator",
"description": "Main channel host",
"images": [
{
"id": "img-1",
"url": "https://...",
"name": "front-face.jpg"
},
{
"id": "img-2",
"url": "https://...",
"name": "side-profile.jpg"
}
],
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-14T12:00:00.000Z"
}
}Erreur : personne introuvable
json
{
"success": false,
"error": "Person not found"
}404 Not Found
Ajouter des images à une personne
Ajoute des images de référence du visage à une personne existante.POST /api/persons/{id}/images
| Paramètre | Type | Description |
|---|---|---|
id | string (UUID) | ID de la personne |
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
imageIds | array | Oui | Tableau d’ID d’assets à ajouter (1 à 10 images) |
Les images doivent d’abord être importées avec l’API Assets. Passe ensuite les ID d’assets obtenus à cet endpoint.
bash
curl -X POST https://youthumb.ai/api/persons/123e4567-e89b-12d3-a456-426614174000/images \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"imageIds": [
"asset-uuid-1",
"asset-uuid-2"
]
}'Réponse d’ajout d’images
json
{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Creator",
"imageCount": 7,
"addedImages": 2
}
}Utiliser les personnes dans la génération de miniatures
Lors de la création d’une miniature, référence une personne de l’une de ces deux façons :Par ID de personne
json
{
"prompt": "Excited reaction to new product",
"personId": "123e4567-e89b-12d3-a456-426614174000"
}Par nom de personne
json
{
"prompt": "Excited reaction to new product",
"personName": "John Creator"
}Tu ne peux pas utiliser
personId et personName dans la même requête. Choisis une seule méthode.Exemple complet : JavaScript
javascript
const API = 'https://youthumb.ai/api';
const headers = {
'x-api-key': process.env.YOUTHUMB_API_KEY,
'Content-Type': 'application/json',
};
// Créer une personne
async function createPerson(name, description) {
const response = await fetch(`${API}/persons`, {
method: 'POST',
headers,
body: JSON.stringify({ name, description }),
});
return response.json();
}
// Lister toutes les personnes
async function listPersons() {
const response = await fetch(`${API}/persons`, { headers });
return response.json();
}
// Obtenir le détail d'une personne
async function getPerson(personId) {
const response = await fetch(`${API}/persons/${personId}`, { headers });
return response.json();
}
// Utilisation
const newPerson = await createPerson('Channel Host', 'Primary presenter');
console.log('Created person:', newPerson.data.id);
const allPersons = await listPersons();
console.log('All persons:', allPersons.data.length);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.