Concepto
Una persona en YouThumbAI:- Es un perfil con nombre asociado a tu organización
- Contiene una o varias imágenes de referencia del rostro
- La usa la IA para generar intercambios de rostro coherentes
- Se puede referenciar por ID o por nombre al crear miniaturas
Para obtener los mejores resultados, sube de 3 a 5 imágenes claras del rostro desde distintos ángulos. Consulta la guía de optimización del perfil de rostro para ver consejos detallados.
Listar personas
Recupera todas las personas de tu organización.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"
}
]
}Crear una persona
Crea un nuevo perfil de persona.POST /api/persons
Cuerpo de la solicitud
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | Sí | Nombre de la persona (1-100 caracteres) |
description | string | No | Descripción (máx. 500 caracteres) |
imageIds | array | No | Array de IDs de recursos subidos que se adjuntan |
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"
]
}'Respuesta de creación
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"
}
}Obtener los detalles de una persona
Recupera los detalles de una persona concreta.GET /api/persons/{id}
| Parámetro | Tipo | Descripción |
|---|---|---|
id | string (UUID) | ID de la persona |
bash
curl https://youthumb.ai/api/persons/123e4567-e89b-12d3-a456-426614174000 \
-H "x-api-key: your_api_key"Respuesta con los detalles de la persona
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"
}
}Error: persona no encontrada
json
{
"success": false,
"error": "Person not found"
}404 Not Found
Añadir imágenes a una persona
Añade imágenes de referencia del rostro a una persona existente.POST /api/persons/{id}/images
| Parámetro | Tipo | Descripción |
|---|---|---|
id | string (UUID) | ID de la persona |
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
imageIds | array | Sí | Array de IDs de recursos que se añaden (1-10 imágenes) |
Primero hay que subir las imágenes con la API de recursos. Pasa los IDs de recurso obtenidos a este 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"
]
}'Respuesta al añadir imágenes
json
{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Creator",
"imageCount": 7,
"addedImages": 2
}
}Usar personas al generar miniaturas
Al crear una miniatura, referencia una persona de una de estas formas:Por ID de persona
json
{
"prompt": "Excited reaction to new product",
"personId": "123e4567-e89b-12d3-a456-426614174000"
}Por nombre de persona
json
{
"prompt": "Excited reaction to new product",
"personName": "John Creator"
}No puedes usar
personId y personName en la misma solicitud. Elige un solo método.Ejemplo completo: JavaScript
javascript
const API = 'https://youthumb.ai/api';
const headers = {
'x-api-key': process.env.YOUTHUMB_API_KEY,
'Content-Type': 'application/json',
};
// Crear una persona
async function createPerson(name, description) {
const response = await fetch(`${API}/persons`, {
method: 'POST',
headers,
body: JSON.stringify({ name, description }),
});
return response.json();
}
// Listar todas las personas
async function listPersons() {
const response = await fetch(`${API}/persons`, { headers });
return response.json();
}
// Obtener los detalles de una persona
async function getPerson(personId) {
const response = await fetch(`${API}/persons/${personId}`, { headers });
return response.json();
}
// Uso
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);Recursos: personas, imágenes y catálogo
Las operaciones usan la identidad conectada. Cada recurso almacenado debe pertenecer a la organización seleccionada y ser tuyo o estar compartido con ella. Las imágenes importadas siguen sin publicar y se pueden encontrar. Un ID inexistente o inaccesible devuelve 404; permisos insuficientes, 403; entrada inválida, 400. MCP devuelveisError: true para errores. Estas operaciones no consumen créditos.
| REST | MCP | Entrada / efecto |
|---|---|---|
PATCH /api/persons/:id | update_person | name? (1–100), description? (máx. 500); null borra descripción; al menos un campo |
DELETE /api/persons/:id | delete_person | Elimina perfil y asociaciones; conserva las imágenes almacenadas |
DELETE /api/persons/:id/images/:imageId | remove_person_image | Desvincula esta asociación existente sin eliminar el recurso |
PUT /api/persons/:id/default | set_default_person | Persona predeterminada de la organización; idempotente y respeta permisos de propietario |
GET /api/assets/:id | get_asset | UUID de un recurso almacenado autorizado |
GET /api/templates/:id | get_template | Plantilla publicada del catálogo o una privada creada por ti |
mcp:assets y acceso Imágenes y personas activo. Las lecturas requieren mcp:read y Lectura activo. Los argumentos MCP son personId, imageId, assetId o templateId en lugar de segmentos URL. Leer/modificar una persona devuelve perfil con images e imageCount; eliminar devuelve {"deleted":true}. Crear y añadir fotos también verifica cada imagen antes de escribir.