URL del servidor
text
https://www.youthumb.ai/api/mcpAñadir YouThumb a tu agente
| Agente | Cómo añadir el servidor |
|---|---|
| Claude | Configuración → Conectores → Añadir conector personalizado, pega la URL del servidor y luego Conectar. |
| ChatGPT | En la configuración de conectores (modo desarrollador), crea un conector con la URL del servidor y autenticación OAuth. |
| Claude Code | claude mcp add --transport http youthumb https://www.youthumb.ai/api/mcp y luego ejecuta /mcp para iniciar sesión. |
| Codex | codex mcp add youthumb --url https://www.youthumb.ai/api/mcp y luego codex mcp login youthumb. |
Iniciar sesión y autorizar
- Tu agente abre una página de YouThumb en tu navegador.
- Inicia sesión con tu correo y contraseña o con Google. El enlace mágico no está disponible para esta conexión.
- YouThumb muestra la aplicación que pide acceso, la dirección a la que te devolverá y los permisos solicitados.
- Elige la Organización usada por esta app: la app trabajará solo en esta organización, con sus créditos. Para cambiarla más tarde, vuelve a conectar la app.
- Elige Autorizar o Rechazar.
Qué puede hacer tu agente
| Permiso | Herramientas |
|---|---|
mcp:read | get_credits, list_persons, get_person, list_assets, list_templates, list_presets, get_generation |
mcp:generate | create_thumbnail_project, start_generation |
mcp:assets | upload_asset, delete_asset, create_person, add_person_images |
Mantén el control de los créditos
Crear un proyecto no consume créditos; lanzar la generación, sí. El agente usa los créditos de la organización que elegiste al autorizarlo. Si se agotan tus créditos, se alcanza un límite de tu plan o hay demasiadas generaciones en curso, la herramienta devuelve un error legible en lugar de generar. ¿Prefieres una clave API y la skillyouthumb-ai? Consulta Agentes.
Biblioteca, favoritos y papelera
Busca proyectos existentes antes de crear otra miniatura.GET /api/thumbnails y list_thumbnail_projects aceptan search, status, favorite y deleted. Las listas usan page (desde 1) y limit (1–100, 20 por defecto); los filtros se aplican antes de paginar. favorite=false selecciona los no favoritos y deleted=true los proyectos en la papelera.
Los favoritos se comparten en la organización seleccionada. Envía {"isFavorite":true} o {"isFavorite":false} explícitamente: repetir la petición no alterna el estado. Renombra con {"projectName":"Nuevo título"}. Gestionar la biblioteca no consume créditos. Las lecturas MCP requieren mcp:read y acceso Lectura; las mutaciones requieren mcp:generate y acceso Generación, además de los permisos normales. Solo los administradores pueden enviar un proyecto completo a la papelera.
Las listas normales y el detalle ocultan los jobs eliminados y los proyectos padres eliminados. list_generations devuelve resultados completados de proyectos de miniaturas visibles, con todas las imágenes de variaciones en el array results de cada job. La papelera acepta kind=projects o kind=jobs (jobs eliminados individualmente, incluso bajo padres eliminados). No hay eliminación permanente. Restaura primero el proyecto y después sus jobs eliminados individualmente. Restaurar un proyecto establece su estado en completed sin restaurar sus hijos. El deletedAt del proyecto deriva de updatedAt; no es un historial inmutable de eliminación. Cada job tiene su propio deletedAt almacenado. Repetir una eliminación/restauración ya realizada conserva las fechas.
No se pueden eliminar jobs activos ni proyectos con jobs activos (409). Restaurar un job bajo un padre eliminado también devuelve 409. Las peticiones inválidas devuelven 400, permisos insuficientes 403, e identificadores desconocidos o de otra organización 404.
GET /api/thumbnails/:projectId, /detailed-status, /status y get_generation comparten el detalle: metadatos del proyecto, isFavorite, resumen global, último resultado, metadatos de jobs, imágenes agrupadas e IDs de personas. Se conservan jobs[].results y activeJobs. Sin opciones se devuelven todos los jobs visibles; page o limit activa páginas limitadas. status solo (valores separados por comas) filtra todos los jobs visibles sin paginarlos, conservando el comportamiento anterior. El resumen y el último resultado siempre abarcan el proyecto visible completo.
| REST | MCP | Parameters |
|---|---|---|
GET /api/thumbnails | list_thumbnail_projects | page, limit, search, status, favorite, deleted |
GET /api/thumbnails/:projectId | get_generation | summary?, page?, limit?, status? |
PATCH /api/thumbnails/:projectId | update_thumbnail_project | projectName |
GET /api/thumbnails/results | list_generations | page, limit, favorite, projectId |
PUT /api/thumbnails/:projectId/favorite | set_project_favorite | isFavorite |
PUT /api/thumbnails/jobs/:jobId/favorite | set_generation_favorite | isFavorite |
DELETE /api/thumbnails/:projectId | trash_thumbnail_project | projectId |
POST /api/thumbnails/:projectId/restore | restore_thumbnail_project | projectId |
DELETE /api/thumbnails/jobs/:jobId | trash_generation | jobId |
POST /api/thumbnails/jobs/:jobId/restore | restore_generation | jobId |
GET /api/thumbnails/trash | list_trash | kind=projects / jobs, page, limit |
json
{"favorite":true,"page":1,"limit":20}Intentos, iteración y reintento
POST /api/thumbnails/:projectId/start y start_generation conservan el proyecto. Opciones: prompt, personId (null elimina), presetKey, templateId, styleReferenceUrl, youtubeUrl, sourceResultId, contentImages ([] elimina), title ("" elimina) y advancedOptions. Los campos omitidos conservan los valores del proyecto; las opciones se combinan. Solo cambia este intento, no el proyecto guardado. Indica una sola fuente (preset, plantilla, URL, YouTube o resultado). Cada imagen contiene exactamente un userImageId o url; las URL explícitas deben pertenecer a tu ruta de almacenamiento configurada. Sube primero las imágenes externas.
Obtén jobs[].results[].id del detalle del proyecto y úsalo como sourceResultId para iterar sobre esa imagen exacta. Debe proceder de un trabajo terminado y visible del mismo proyecto. Una referencia selecciona generación normal; un preset, generación mágica. Se rechazan proyectos y resultados eliminados.
json
{"projectId":"<project-id>","sourceResultId":"<result-image-id>","prompt":"Conserva la composición y aclara el fondo","advancedOptions":{"variations":1}}POST /api/thumbnails/jobs/:jobId/retry / retry_generation({jobId}) acepta solo trabajos Default fallidos. Crea un nuevo intento facturado en el mismo proyecto con el prompt, imágenes de entrada, personas, título, preset y opciones originales. No reinicia el trabajo fallido ni usa los valores actuales del proyecto. Registra retryOfJobId. Cada llamada vuelve a consumir créditos: no es idempotente. Devuelve jobId, projectId, status, creditsConsumed tras confirmar el lanzamiento. Un fallo síncrono reembolsa y marca el trabajo huérfano como fallido.
Ayuda con el prompt
POST /api/thumbnails/prompts/improve / improve_prompt: prompt y context opcional con axes (composition, hook, readability), language (fr, en, es), personName, title, customInstruction, hasStyleReference, referenceTokens (@image1...), sketchTokens (@sketch1...).
POST /api/thumbnails/prompts/from-reference / prompt_from_reference: una sola fuente entre assetId, templateId publicado o privado creado por ti, projectId + sourceResultId, o imageUrl cuya pertenencia a las subidas del usuario esté verificada. language opcional, en por defecto. No acepta URL arbitrarias: sube primero la imagen. Las referencias se autorizan en la organización seleccionada antes del cobro.
Ambos devuelven {prompt, creditsConsumed: 0.5} sin crear un proyecto ni una imagen. Un error del proveedor reembolsa una vez. MCP exige mcp:generate y generación habilitada. El límite diario contabiliza medios créditos exactos; cambiar de herramienta no elude el límite. Los límites enteros existentes conservan su significado.
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}'Exploración compacta y contadores explícitos
Para explorar o consultar el progreso, usaget_generation({projectId, summary:true, page:1, limit:5}) o GET /api/thumbnails/:projectId?summary=true&page=1&limit=5. summary=true aplica página 1 y límite 20 por defecto (1–100); status admite estados separados por comas. La respuesta contiene projectId, projectName, status, isFavorite, el summary global del proyecto, pagination y jobs con solo jobId, status, type, isFavorite, userPrompt, generatedFileUrl, createdAt. Omite metadatos, imágenes incrustadas y personas. Conserva los prompts completos: no garantiza un tamaño máximo en bytes. Sigue pagination.hasMore. Para obtener IDs de imágenes para sourceResultId, solicita una página detallada acotada con summary:false.
Sin summary, o con false, se conserva el contrato detallado anterior, incluidas las lecturas sin límite con solo status. list_generations / GET /api/thumbnails/results incluye el userPrompt completo (o null) por job, sin consultar el detalle.
get_credits / GET /api/usage añade counts.activeGenerationProjects (proyectos no eliminados, todos los tipos) y counts.completedThumbnailJobs (jobs completados no eliminados en proyectos de miniaturas visibles, mismo alcance que list_generations sin filtros). Son contadores de la organización: proyectos y jobs, no imágenes ni créditos consumidos. Las estadísticas anteriores generations siguen contando proyectos; generations.total equivale a counts.activeGenerationProjects. Los créditos y contadores anteriores no cambian.
Los favoritos de proyecto (generation_project), job (generation_job) y archivo bucket personal son independientes. list_thumbnail_projects({favorite:true}) puede devolver cero aunque existan muchos jobs favoritos: no selecciona proyectos solo por contener un job favorito. Si faltan los parámetros summary, page, limit o search de assets, actualiza/reconecta el cliente MCP y recarga su lista de herramientas. Actualizar únicamente el skill no renueva los esquemas almacenados en caché.