API de personas | YouThumbAI Documentation

La API de personas te permite gestionar perfiles de rostro que se pueden usar para el intercambio de rostro con IA al generar miniaturas. Una "persona" representa un perfil de rostro con varias imágenes de referencia.

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

Básico:

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

Con imágenes:

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

Código de estado: 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);