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
Lista tus imágenes almacenadas o compartidas con la organización, incluidas las no publicadas.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.
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.
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}'