API de recursos

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

TipoDescripciónGuardado en BD
faceImágenes de referencia del rostro para las personasSí
templatePlantillas de referencia de estiloSí
bucketSubida 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

Lista tus imágenes almacenadas o compartidas con la organización, incluidas las no publicadas.
GET /api/assets

Parámetros de consulta

ParámetroTipoObligatorioPor defectoDescripción
typestringNo-Filtrar por tipo: face, template, bucket
pagenumberNo1Número de página
limitnumberNo20Elementos 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)

CampoTipoObligatorioDescripción
fileFileSíArchivo de imagen (el MIME debe empezar por image/)
typestringSíface, template o bucket
descriptionstringNoDescripció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)

CampoTipoObligatorioPor defectoDescripción
base64stringSí-Imagen codificada en base64 (con o sin el prefijo data:)
typestringSí-face, template o bucket
filenamestringNogenerado automáticamenteNombre del archivo
mimeTypestringNoimage/jpegimage/jpeg, image/png, image/webp, image/gif
descriptionstringNo-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ámetroTipoDescripción
idstring (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ámetroTipoDescripción
idstring (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.
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.

Encontrar imágenes importadas

GET /api/assets / list_assets acepta type (face, template, bucket), search, isPublished, page (1 por defecto), limit (20, máx. 100). Sin type, lista imágenes face/template almacenadas. Busca en nombre/descripción; visibilidad y filtros se aplican antes de paginar y contar. Cada recurso incluye isPublished, ownerScope: "organization". Paginación: page, limit, total, totalPages, hasMore. type=bucket lista la carpeta temporal personal del usuario, compartida entre sus organizaciones. Cada resultado incluye ownerScope: "user", id: "", fileKey estable, url e isFavorite. Usa contentImages: [{"url": "URL_DEVUELTA"}] para generar; get_asset y userImageId requieren un UUID de recurso persistido, nunca una clave bucket. favorite=true selecciona favoritos y favorite=false los excluye; sin filtro se incluyen ambos. search busca nombres de archivo. Solo para bucket, sortBy=name|createdAt y sortOrder=asc|desc usan por defecto createdAt descendente. Las fechas ausentes o inválidas mantienen createdAt: null y van al final en ambos sentidos; los empates se ordenan por fileKey ascendente. Estos tres filtros se rechazan para otros tipos; isPublished es inválido para bucket. El servicio recorre todos los archivos coincidentes en lotes de 100, elimina duplicados por ruta y excluye archivos que no sean imágenes y marcadores antes de filtrar favoritos, ordenar y paginar. total cuenta las imágenes filtradas, totalPages = ceil(total / limit) y hasMore indica otra página. Una lista vacía tiene totales de 0; una página fuera de rango está vacía. Los favoritos huérfanos no crean recursos. Cada consulta enumera la carpeta coincidente: las carpetas grandes requieren más llamadas al almacenamiento; los cambios concurrentes no ofrecen un snapshot atómico. El fallo de cualquier página del proveedor hace fallar toda la consulta, sin éxito parcial. No se eliminan archivos temporales con /api/assets/:id. Ejemplo: GET /api/assets?type=bucket&search=logo&favorite=true&sortBy=createdAt&sortOrder=desc&page=1&limit=20 o MCP list_assets({"type":"bucket","search":"logo","favorite":true,"sortBy":"createdAt","sortOrder":"desc","page":1,"limit":20}).

Tres tipos de identificadores

GET /api/templates / list_templates busca título, descripción y etiquetas del catálogo con search. scope=public (predeterminado) lista plantillas publicadas; scope=mine solo tus creaciones, públicas o privadas. isPublished=false exige scope=mine. Se conservan category, isFeatured, page, limit. Respuesta: templates y pagination (page, limit, total, totalPages). Un UUID del catálogo se usa como templateId. Una referencia importada se encuentra con list_assets(type="template"): usa su URL como styleReferenceUrl, o su UUID como userImageId de contenido / assetId de asistencia al prompt. Un archivo temporal usa su URL. No intercambies IDs del catálogo, IDs de recursos y claves de archivos.
bash
curl "$BASE/api/assets?type=template&search=studio&page=1&limit=20" -H "x-api-key: $YOUTHUMB_API_KEY"
curl "$BASE/api/templates?scope=mine&isPublished=false&search=studio" -H "x-api-key: $YOUTHUMB_API_KEY"
curl -X PATCH "$BASE/api/persons/$PERSON_ID" -H "x-api-key: $YOUTHUMB_API_KEY" -H "Content-Type: application/json" -d '{"description":null}'