API Persons

L’API Persons te permet de gérer les profils de visage utilisables pour le face swap par IA lors de la génération de miniatures. Une « personne » représente un profil de visage avec plusieurs images de référence.

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ètreTypeObligatoireDescription
namestringOuiNom de la personne (1-100 caractères)
descriptionstringNonDescription (500 caractères max)
imageIdsarrayNonTableau d’ID d’assets importés à rattacher
Basique :
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"
  }'
Avec images :
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ètreTypeDescription
idstring (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"
}
Code de statut : 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ètreTypeDescription
idstring (UUID)ID de la personne
ParamètreTypeObligatoireDescription
imageIdsarrayOuiTableau 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 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.