API de personas

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ámetroTipoObligatorioDescripción
namestringSíNombre de la persona (1-100 caracteres)
descriptionstringNoDescripción (máx. 500 caracteres)
imageIdsarrayNoArray 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ámetroTipoDescripción
idstring (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ámetroTipoDescripción
idstring (UUID)ID de la persona
ParámetroTipoObligatorioDescripción
imageIdsarraySí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);
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 devuelve isError: true para errores. Estas operaciones no consumen créditos.
RESTMCPEntrada / efecto
PATCH /api/persons/:idupdate_personname? (1–100), description? (máx. 500); null borra descripción; al menos un campo
DELETE /api/persons/:iddelete_personElimina perfil y asociaciones; conserva las imágenes almacenadas
DELETE /api/persons/:id/images/:imageIdremove_person_imageDesvincula esta asociación existente sin eliminar el recurso
PUT /api/persons/:id/defaultset_default_personPersona predeterminada de la organización; idempotente y respeta permisos de propietario
GET /api/assets/:idget_assetUUID de un recurso almacenado autorizado
GET /api/templates/:idget_templatePlantilla publicada del catálogo o una privada creada por ti
Las mutaciones MCP requieren 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.