API Thumbnails

L’API Thumbnails te permet de créer, générer et gérer des miniatures par IA depuis ton code.

URL de base

https://youthumb.ai/api/thumbnails

Vue d’ensemble des endpoints

Méthode	Endpoint	Description
POST	/thumbnails	Créer un nouveau projet de miniature
POST	/thumbnails/:projectId/start	Lancer la génération
GET	/thumbnails/:projectId/status	Obtenir le statut de la génération
GET	/thumbnails/:projectId/detailed-status	Obtenir le statut détaillé avec les images

POST /thumbnails

Crée un nouveau projet de miniature.

bash

curl -X POST https://youthumb.ai/api/thumbnails \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Excited creator with bright yellow background",
    "presetKey": "mrbeast-viral"
  }'

Corps de la requête

Paramètre	Type	Obligatoire	Description
`prompt`	string	Oui	Description de la miniature (3-2000 caractères)
`personId`	uuid	Non	ID de la personne pour le face swap
`personName`	string	Non	Nom de la personne (alternative à personId)
`presetKey`	string	Non	Preset de style (voir Presets)
`templateId`	uuid	Non	ID du template servant de référence de style
`styleReferenceUrl`	url	Non	URL d’une image externe servant de référence de style
`youtubeUrl`	url	Non	URL YouTube dont extraire la miniature
`contentImages`	array	Non	Images supplémentaires (6 max)
`title`	string	Non	Texte incrusté (200 caractères max)
`projectName`	string	Non	Nom du projet (100 caractères max)
`advancedOptions`	object	Non	Options de génération avancées

Options avancées

Option	Type	Valeurs
`variations`	number	`1`, `2`, `3`, `4`
`faceExpression`	string	`neutral`, `happy`, `surprised`, `excited`, `serious`, `confident`, `keep-original`
`textPosition`	string	`top`, `center`, `bottom`, `none`, `keep-original`
`negativePrompt`	string	Ce qu’il faut éviter (500 caractères max)
`clothingStyle`	string	`casual`, `professional`, `sporty`, `elegant`, `streetwear`, `keep-original`
`faceEnhancement`	string	`subtle`, `normal`, `enhanced`, `keep-original`
`backgroundBlur`	number	`0` - `100`

Réponse `201 Created`

json

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "draft",
    "projectName": "Untitled Project",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

POST /thumbnails/:projectId/start

Lance la génération par IA. Cette action consomme des crédits.

bash

curl -X POST https://youthumb.ai/api/thumbnails/:projectId/start \
  -H "x-api-key: your_api_key"

Options de remplacement

Remplace des options au lancement :

json

{
  "prompt": "Override the original prompt",
  "advancedOptions": {
    "variations": 4
  }
}

Réponse en cas de succès `200 OK`

json

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "creditsConsumed": 1,
    "message": "Generation started"
  }
}

Réponse d’erreur `402 Payment Required`

json

{
  "success": false,
  "error": "Insufficient credits"
}

GET /thumbnails/:projectId/status

Obtiens le statut du projet et ses jobs. Pagination et filtre par statut optionnels.

bash

# Basique (renvoie tous les jobs, rétrocompatible)
curl https://youthumb.ai/api/thumbnails/:projectId/status \
  -H "x-api-key: your_api_key"

# Avec pagination
curl "https://youthumb.ai/api/thumbnails/:projectId/status?page=1&limit=20" \
  -H "x-api-key: your_api_key"

# Avec filtre par statut
curl "https://youthumb.ai/api/thumbnails/:projectId/status?status=completed&page=1&limit=10" \
  -H "x-api-key: your_api_key"

# Filtre sur plusieurs statuts
curl "https://youthumb.ai/api/thumbnails/:projectId/status?status=pending,processing" \
  -H "x-api-key: your_api_key"

Paramètres de requête

Paramètre	Type	Défaut	Description
`page`	number	`1`	Numéro de page (commence à 1)
`limit`	number	`20`	Éléments par page (100 max)
`status`	string	—	Filtre par statut de job. Séparés par des virgules pour plusieurs : `pending,processing`

Remarque : sans page ni limit, tous les jobs sont renvoyés sans pagination (comportement rétrocompatible).

Réponse (sans pagination)

json

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "projectName": "My Thumbnail",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ]
  }
}

Réponse (avec pagination)

json

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "projectName": "My Thumbnail",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

Valeurs de statut

Statut	Description
`draft`	Projet créé, pas encore lancé
`processing`	Génération en cours
`completed`	Tous les jobs sont terminés
`failed`	La génération a échoué

GET /thumbnails/:projectId/detailed-status

Obtiens le statut détaillé avec toutes les images générées.

bash

curl https://youthumb.ai/api/thumbnails/:projectId/detailed-status \
  -H "x-api-key: your_api_key"

Réponse détaillée

json

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "projectName": "My Thumbnail",
    "status": "completed",
    "summary": {
      "totalJobs": 1,
      "activeJobs": 0,
      "completedJobs": 1,
      "failedJobs": 0,
      "totalVariations": 4
    },
    "latestGeneratedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "type": "thumbnail-generation",
        "userPrompt": "Excited creator with yellow background",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "images": {
          "styleReference": [],
          "content": [],
          "faces": [
            {
              "id": "face-001",
              "url": "https://storage.youthumb.ai/faces/face.jpg",
              "name": "face.jpg"
            }
          ],
          "results": [
            {
              "id": "result-001",
              "url": "https://storage.youthumb.ai/results/var1.png",
              "width": 1280,
              "height": 720
            },
            {
              "id": "result-002",
              "url": "https://storage.youthumb.ai/results/var2.png",
              "width": 1280,
              "height": 720
            }
          ]
        },
        "personIds": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"],
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Exemple de workflow complet

javascript

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

// 1. POST - Créer le projet
const create = await fetch(`${API}/thumbnails`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    prompt: 'Excited tech reviewer with product',
    presetKey: 'tech-review',
    advancedOptions: { variations: 2 }
  }),
});
const { data: project } = await create.json();

// 2. POST - Lancer la génération
await fetch(`${API}/thumbnails/${project.projectId}/start`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY },
});

// 3. GET - Interroger le statut
let status = 'processing';
while (status === 'processing') {
  await new Promise(r => setTimeout(r, 3000));

  const res = await fetch(`${API}/thumbnails/${project.projectId}/status`, {
    headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY },
  });
  const data = await res.json();
  status = data.data.status;
}

// 4. GET - Récupérer les résultats
const results = await fetch(
  `${API}/thumbnails/${project.projectId}/detailed-status`,
  { headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY } }
);
const { data: final } = await results.json();

console.log('Generated images:', final.jobs[0].images.results);

Bibliothèque, favoris et corbeille

Retrouvez les projets existants avant de créer une nouvelle miniature. GET /api/thumbnails et list_thumbnail_projects acceptent search, status, favorite et deleted. Les listes utilisent page (à partir de 1) et limit (1–100, 20 par défaut), avec les filtres appliqués avant pagination. favorite=false sélectionne les non-favoris ; deleted=true sélectionne les projets à la corbeille. Les favoris sont partagés par l’organisation sélectionnée. Envoyez explicitement {"isFavorite":true} ou {"isFavorite":false} : une répétition ne bascule pas l’état. Renommez avec {"projectName":"Nouveau titre"}. La gestion de bibliothèque ne consomme aucun crédit. En MCP, les lectures demandent mcp:read et le droit Lecture ; les mutations demandent mcp:generate et le droit Génération, ainsi que les permissions habituelles du compte. Seuls les administrateurs peuvent mettre un projet entier à la corbeille. Les listes normales et le détail masquent les jobs supprimés et les projets parents supprimés. list_generations renvoie les résultats terminés des projets miniatures visibles, avec toutes les images de variations dans le tableau results de chaque job. La corbeille accepte kind=projects ou kind=jobs (jobs supprimés individuellement, y compris sous un parent supprimé). Aucune suppression définitive. Restaurez d’abord le projet, puis les jobs supprimés individuellement. La restauration d’un projet fixe son statut à completed, sans restaurer ses enfants. Le deletedAt du projet est dérivé de updatedAt, pas un historique immuable de suppression. Le job possède son propre deletedAt stocké. Répéter une suppression/restauration déjà effectuée préserve les horodatages. Un job actif ou un projet avec des jobs actifs ne peut pas être supprimé (409). Restaurer un job sous un parent supprimé renvoie aussi 409. Une requête invalide renvoie 400, un droit insuffisant 403, un identifiant inconnu ou d’une autre organisation 404. GET /api/thumbnails/:projectId, /detailed-status, /status et get_generation partagent le détail : métadonnées projet, isFavorite, résumé global, dernier résultat, métadonnées des jobs, images groupées et IDs des personnes. jobs[].results et activeJobs restent disponibles. Sans option, tous les jobs visibles sont renvoyés ; page ou limit active la pagination bornée. status seul (valeurs séparées par des virgules) filtre tous les jobs visibles sans les paginer, pour préserver les clients existants. Le résumé et le dernier résultat restent globaux au projet visible.

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}

Essais, itération et relance

POST /api/thumbnails/:projectId/start et start_generation conservent le même projet. Paramètres facultatifs : prompt, personId (null efface), presetKey, templateId, styleReferenceUrl, youtubeUrl, sourceResultId, contentImages ([] efface), title ("" efface) et advancedOptions. Les champs omis reprennent les réglages du projet ; les options fusionnent. Ces changements concernent uniquement cet essai, pas le projet enregistré. Fournir une seule source (preset, template, URL, YouTube ou résultat). Chaque image de contenu contient exactement un userImageId ou url ; les URL explicites doivent appartenir au chemin de stockage configuré de vos imports. Importer les images externes avant utilisation. Lire jobs[].results[].id dans le détail du projet, puis passer cet identifiant dans sourceResultId pour itérer sur cette image exacte. Elle doit provenir d'un job terminé, visible, du même projet. Une référence sélectionne le mode normal ; un preset, le mode magique. Les projets et résultats supprimés sont refusés.

json

{"projectId":"<project-id>","sourceResultId":"<result-image-id>","prompt":"Garde cette composition et éclaircis le fond","advancedOptions":{"variations":1}}

POST /api/thumbnails/jobs/:jobId/retry / retry_generation({jobId}) accepte uniquement un job Default échoué. Il crée un nouvel essai facturé dans le même projet, en conservant prompt, images d'entrée, personnes, titre, preset et options de l'essai échoué. Il ne réinitialise pas l'ancien job et ne reprend pas les réglages actuels du projet. Les métadonnées portent retryOfJobId. Chaque appel consomme de nouveaux crédits : l'opération n'est pas idempotente. Le succès renvoie jobId, projectId, status, creditsConsumed seulement après confirmation du lancement. Un échec synchrone rembourse et marque le job orphelin échoué.

Aide au prompt

POST /api/thumbnails/prompts/improve / improve_prompt : prompt et context facultatif avec 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 : une seule source parmi assetId, templateId publié ou privé créé par vous, projectId + sourceResultId, ou imageUrl dont l'appartenance aux imports de l'appelant est prouvée. language facultatif, en par défaut. Les URL arbitraires sont refusées : importer d'abord. Les références sont autorisées dans l'organisation sélectionnée avant facturation. Les deux renvoient {prompt, creditsConsumed: 0.5}, sans créer de projet ni d'image. Un échec fournisseur rembourse une fois. MCP exige mcp:generate et la génération activée. Le plafond quotidien compte exactement les demi-crédits ; changer d'outil ne permet pas de le contourner. Les plafonds entiers existants gardent leur signification.

Exploration compacte et compteurs explicites

Pour explorer ou suivre une génération, préférez get_generation({projectId, summary:true, page:1, limit:5}) ou GET /api/thumbnails/:projectId?summary=true&page=1&limit=5. summary=true applique page 1 et limit 20 par défaut (1–100) ; status accepte toujours plusieurs statuts séparés par des virgules. La réponse contient projectId, projectName, status, isFavorite, le summary global du projet, pagination et des jobs limités à jobId, status, type, isFavorite, userPrompt, generatedFileUrl, createdAt. Métadonnées, images embarquées et personnes sont omises. Les prompts restent complets : aucune taille maximale en octets n’est garantie. Suivez pagination.hasMore. Pour obtenir les IDs des images nécessaires à sourceResultId, demandez une page détaillée bornée avec summary:false. Sans summary, ou avec false, le contrat détaillé historique est conservé, y compris les lectures non bornées avec status seul. list_generations / GET /api/thumbnails/results expose désormais le userPrompt complet (ou null) par job, sans appel au détail. get_credits / GET /api/usage ajoute counts.activeGenerationProjects (projets non supprimés, tous types) et counts.completedThumbnailJobs (jobs terminés non supprimés de projets miniatures visibles, même périmètre que list_generations sans filtre). Ces compteurs sont propres à l’organisation : projets et jobs, pas images ni crédits consommés. Les statistiques historiques generations comptent toujours des projets ; generations.total égale counts.activeGenerationProjects. Crédits et anciens compteurs restent inchangés. Les favoris projet (generation_project), job (generation_job) et fichier bucket personnel sont distincts. list_thumbnail_projects({favorite:true}) peut normalement renvoyer zéro malgré de nombreux jobs favoris : ce filtre ne sélectionne pas les projets contenant simplement un job favori. Si summary, page, limit ou search des assets sont absents des paramètres disponibles, actualisez/reconnectez le client MCP et rechargez sa liste d’outils. La mise à jour du skill seule ne rafraîchit pas les schémas en cache.

URL de base

Vue d’ensemble des endpoints

POST /thumbnails

Corps de la requête

Options avancées

Réponse 201 Created

POST /thumbnails/:projectId/start

Options de remplacement

Réponse en cas de succès 200 OK

Réponse d’erreur 402 Payment Required

GET /thumbnails/:projectId/status

Paramètres de requête

Réponse (sans pagination)

Réponse (avec pagination)

Valeurs de statut

GET /thumbnails/:projectId/detailed-status

Réponse détaillée

Exemple de workflow complet

Bibliothèque, favoris et corbeille

Essais, itération et relance

Aide au prompt

Exploration compacte et compteurs explicites

Réponse `201 Created`

Réponse en cas de succès `200 OK`

Réponse d’erreur `402 Payment Required`