API de recursos | YouThumbAI Documentation

La API de recursos te permite subir y gestionar las imágenes que se usan en YouThumbAI. Los recursos son la base de los perfiles de rostro y de las plantillas personalizadas.

Tipos de recurso

Tipo	Descripción	Guardado en BD
`face`	Imágenes de referencia del rostro para las personas	Sí
`template`	Plantillas de referencia de estilo	Sí
`bucket`	Subida de archivo temporal (sin entrada en BD)	No

El tipo bucket sube archivos a un almacenamiento temporal sin crear una entrada en la base de datos. Útil para imágenes transitorias que se necesitan durante los flujos de generación.

Listar recursos

Recupera los recursos compartidos y publicados en tu organización.

GET /api/assets

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Por defecto	Descripción
`type`	string	No	-	Filtrar por tipo: `face`, `template`, `bucket`
`page`	number	No	1	Número de página
`limit`	number	No	20	Elementos por página (máx. 100)

bash

# Listar todos los recursos
curl https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key"

# Listar solo los recursos de rostro
curl "https://youthumb.ai/api/assets?type=face" \
  -H "x-api-key: your_api_key"

# Paginado
curl "https://youthumb.ai/api/assets?page=2&limit=10" \
  -H "x-api-key: your_api_key"

Respuesta de la lista

json

{
  "success": true,
  "data": {
    "assets": [
      {
        "id": "asset-uuid",
        "type": "face",
        "url": "https://...",
        "name": "photo.jpg",
        "description": "Front face photo",
        "mimeType": "image/jpeg",
        "size": 245000,
        "width": 1920,
        "height": 1080,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20
    }
  }
}

Subir un recurso

Sube una imagen. Admite dos modos: multipart/form-data y JSON (base64).

POST /api/assets

Modo 1: multipart (FormData)

Campo	Tipo	Obligatorio	Descripción
`file`	File	Sí	Archivo de imagen (el MIME debe empezar por `image/`)
`type`	string	Sí	`face`, `template` o `bucket`
`description`	string	No	Descripción

bash

curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -F "file=@face-photo.jpg" \
  -F "type=face" \
  -F "description=Front face photo"

Modo 2: base64 (JSON)

Campo	Tipo	Obligatorio	Por defecto	Descripción
`base64`	string	Sí	-	Imagen codificada en base64 (con o sin el prefijo `data:`)
`type`	string	Sí	-	`face`, `template` o `bucket`
`filename`	string	No	generado automáticamente	Nombre del archivo
`mimeType`	string	No	`image/jpeg`	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
`description`	string	No	-	Descripción (máx. 500 caracteres)

bash

curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "type": "face",
    "filename": "my-face.jpg",
    "mimeType": "image/jpeg",
    "description": "Front face photo"
  }'

Respuesta de subida

json

{
  "success": true,
  "data": {
    "id": "new-asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "my-face.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

En las subidas bucket, la respuesta tiene un id vacío y null en width/height, ya que el archivo se guarda temporalmente sin registro en la base de datos.

Obtener un recurso

Recupera un recurso concreto por su ID.

GET /api/assets/{id}

Parámetro	Tipo	Descripción
`id`	string (UUID)	ID del recurso

bash

curl https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Respuesta de obtención

json

{
  "success": true,
  "data": {
    "id": "asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "photo.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Eliminar un recurso

Elimina un recurso por su ID.

DELETE /api/assets/{id}

Parámetro	Tipo	Descripción
`id`	string (UUID)	ID del recurso

bash

curl -X DELETE https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Respuesta de eliminación

json

{
  "success": true,
  "data": {
    "message": "Asset deleted"
  }
}

Ejemplo completo: JavaScript

javascript

const API = 'https://youthumb.ai/api';
const headers = {
  'x-api-key': process.env.YOUTHUMB_API_KEY,
  'Content-Type': 'application/json',
};

// Subir una imagen de rostro (base64)
async function uploadFaceImage(base64Data, filename) {
  const response = await fetch(`${API}/assets`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      base64: base64Data,
      type: 'face',
      filename,
      mimeType: 'image/jpeg',
    }),
  });
  return response.json();
}

// Listar todos los recursos de rostro
async function listFaceAssets() {
  const response = await fetch(`${API}/assets?type=face`, { headers });
  return response.json();
}

// Subir el rostro y luego crear la persona
async function setupPerson(name, faceImages) {
  // 1. Subir todas las imágenes de rostro
  const uploadResults = await Promise.all(
    faceImages.map((img) => uploadFaceImage(img.base64, img.filename))
  );

  const imageIds = uploadResults.map((r) => r.data.id);

  // 2. Crear la persona con las imágenes subidas
  const person = await fetch(`${API}/persons`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ name, imageIds }),
  });

  return person.json();
}

Los recursos son el requisito previo de la API de personas. Primero sube las imágenes de rostro como recursos y luego pasa sus IDs al crear o actualizar una persona.