API Persons | YouThumbAI Documentation

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è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

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è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"
}

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è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);