Extraire des vignettes de vidéos
Le Robot đ€/video/thumbs extrait un nombre quelconque dâimages de vidĂ©os pour les utiliser comme aperçus.

DĂ©finissez smart: true pour sĂ©lectionner par IA des images dâaperçu pertinentes au lieu dâextraire des images uniquement Ă intervalles rĂ©guliers. Le Robot Ă©value les images candidates selon leur nettetĂ©, leur luminositĂ©, leur composition, les visages, les expressions, lâaction et lâintĂ©rĂȘt visuel, puis renvoie les count meilleures images dans lâordre chronologique. Les rĂ©sultats de la sĂ©lection intelligente incluent file.meta.smart_score et file.meta.smart_reasons. Si lâĂ©valuation par IA nâest pas disponible, lâAssembly continue avec les images candidates dans lâordre de repli et inclut un avertissement. Aucune information dâidentification IA nâest requise.
Les images des vidĂ©os HDR HLG et PQ font lâobjet dâun mappage tonal vers le SDR sRGB avant lâencodage de lâimage, y compris les images candidates des vignettes intelligentes. Cela prĂ©serve lâapparence prĂ©vue dans les navigateurs qui affichent les vignettes en tant quâimages sRGB. Les entrĂ©es SDR conservent leur traitement existant.
Tarification de lâIA
Les frais de traitement habituels de /video/thumbs sâappliquent toujours. Lâanalyse des images par IA est facturĂ©e sĂ©parĂ©ment au coĂ»t du fournisseur sous-jacent, majorĂ© dâune marge Transloadit de 50 %. La sĂ©lection intelligente utilise le modĂšle de vision dĂ©diĂ© openai/gpt-5.4-mini avec le niveau de raisonnement low, indĂ©pendamment du modĂšle par dĂ©faut du Robot /ai/chat. Le montant exact des frais dâIA varie selon le nombre dâimages candidates et la tarification du fournisseur.
LâIA Ă©value des copies dâaperçu limitĂ©es Ă 512 pixels sur le cĂŽtĂ© le plus long, en prĂ©servant le rapport hauteur/largeur et sans agrandir les images plus petites. Les vignettes renvoyĂ©es conservent les dimensions et le format de sortie demandĂ©sâŻ; des sorties plus grandes nâagrandissent pas lâaperçu dâĂ©valuation au-delĂ de cette limite.
smart_max_candidates est le principal levier de contrĂŽle du coĂ»t et de la latence. Le Robot analyse jusquâĂ trois images candidates par vignette demandĂ©e, dans la limite de smart_max_candidates, mais jamais moins que count. Avec les valeurs par dĂ©faut count: 8 et smart_max_candidates: 20, il analyse 20 images et renvoie les 8 meilleures. RĂ©duisez la limite dâimages candidates pour diminuer le coĂ»t et la latence de lâIA. Lâaugmenter peut Ă©largir lâensemble des images candidates jusquâĂ trois fois countâŻ; des limites plus Ă©levĂ©es nâont aucun effet.
Utilisez count avec la sélection intelligente. Pour extraire systématiquement des horodatages exacts avec offsets, définissez smart: false.
MĂȘme si les vignettes sont extraites des vidĂ©os en parallĂšle, nous les trions avant de les ajouter aux rĂ©sultats de lâAssembly. Lâordre dans lequel elles y apparaissent reflĂšte donc leur ordre dâapparition dans la vidĂ©o. Vous pouvez Ă©galement le vĂ©rifier Ă lâaide de la clĂ© de mĂ©tadonnĂ©es thumb_index.
Pour un Template qui gĂ©nĂšre une image dâaffiche Ă partir dâun tĂ©lĂ©versement, lâutilisation des SDK et les vĂ©rifications avant publication, consultez le guide du flux de travail vidĂ©o HTML. La dĂ©mo vidĂ©o et S3 (English) comprend une entrĂ©e enregistrĂ©e et des images extraites.
Exemple dâutilisation
Sélectionner par IA trois vignettes visuellement attrayantes dans chaque vidéo téléversée :
{
"steps": {
"thumbnailed": {
"count": 3,
"ffmpeg_stack": "v7",
"robot": "/video/thumbs",
"smart": true,
"smart_max_candidates": 12,
"use": ":original"
}
}
}ParamĂštres
interpolateboolean | Record<string, boolean>DĂ©termine si les Assembly Variables sont interpolĂ©es pour chaque champ dâinstruction.
Par dĂ©faut, la plupart des champs dâinstruction des Robots interpolent les Assembly Variables. DĂ©finissez ce paramĂštre sur
falsepour traiter tous les champs dâinstruction comme du texte littĂ©ral, ou dĂ©finissez le chemin dâun champ individuel surfalsepour traiter uniquement ce champ comme du texte littĂ©ral. Pour les champs propres Ă un Robot qui sont littĂ©raux par dĂ©faut, dĂ©finissez ce paramĂštre surtrueou dĂ©finissez le chemin de ce champ surtruepour rĂ©activer lâinterpolation.Utilisez des noms de champs tels que
path, ou des chemins avec points tels queffmpeg.vfpour les objets imbriqués.output_metaRecord<string, boolean> | boolean | Array<string>Demande des métadonnées coûteuses en CPU, désactivées par défaut pour accélérer les Assemblies.
Pour les images,
"has_transparency": truedĂ©tecte la transparence et"dominant_colors": trueextrait les couleurs hexadĂ©cimales. Ajoutez"dominant_colors_sampled": truepour obtenir plus rapidement des couleurs approximatives Ă partir de versions rĂ©duites de lâimage. LâĂ©chantillonnage nĂ©cessitedominant_colorset ne modifie ni les octets de lâimage ni la facturation. Sa mĂ©thode et sa palette peuvent varier. Omettez-le ou dĂ©sactivez-le pour obtenir des couleurs en pleine rĂ©solution.Pour les images, vous pouvez Ă©galement ajouter
"blurhash": truepour extraire une chaĂźne BlurHash â une reprĂ©sentation compacte dâun espace rĂ©servĂ© pour lâimage, utile pour afficher un aperçu flou pendant le chargement de lâimage complĂšte.Pour les images,
"thumbhash": trueextrait plutĂŽt un ThumbHash encodĂ© en base64 dansmeta.thumbhash, accompagnĂ© demeta.has_alpha(qui indique si un canal alpha existe, mĂȘme lorsque lâimage est entiĂšrement opaque). Il dĂ©crit les pixels orientĂ©s selon les donnĂ©es EXIF et utilise la premiĂšre image des images animĂ©es. Lâextraction est effectuĂ©e au mieux : les images de plus de 40 mĂ©gapixels, les formats non pris en charge ou un Ă©chec de dĂ©codage ou un dĂ©codage limitĂ© ne produisent aucun espace rĂ©servĂ©. Une extraction rĂ©ussie ajoute des frais de mĂ©tadonnĂ©es Ă©quivalents Ă 20 % des octets de ce fichier. Aucun supplĂ©ment ThumbHash ne sâapplique lorsque lâoption est dĂ©sactivĂ©e ou lorsquâaucun hash nâest produit.DĂ©finissez cette option sur le Step qui produit lâimage, par exemple
/upload/handlepour les originaux tĂ©lĂ©versĂ©s ou/image/resizepour les sorties traitĂ©es. La dĂ©finir uniquement sur/transloadit/storene demande pas lâextraction : le stockage conserve les mĂ©tadonnĂ©es du Step producteur. Transloadit Storage conserve un hash gĂ©nĂ©rĂ© avec sa version immuable et le renvoie dans les rĂ©sultats stockĂ©s et lors des lectures natives de ressources. Les tĂ©lĂ©versements directs vers S3 ne gĂ©nĂšrent pas dâespaces rĂ©servĂ©s. Un espace rĂ©servĂ© contient des informations sur lâimage : protĂ©gez-le donc avec les mĂȘmes contrĂŽles dâaccĂšs que lâimage complĂšte.Pour les vidĂ©os, vous pouvez ajouter le paramĂštre
"colorspace": truepour extraire lâespace colorimĂ©trique de la vidĂ©o de sortie.Pour les vidĂ©os, vous pouvez Ă©galement ajouter
"interlaced": truepour dĂ©tecter si la vidĂ©o est entrelacĂ©e. Cette option combine lâindicateur ffprobe peu coĂ»teuxfield_orderavec une passe dâĂ©chantillonnageidetlimitĂ©e sur les premiĂšres images de la source, et exposeinterlaced,field_orderainsi quâun objet de diagnosticinterlace_detectionsousfile.meta. Cette opĂ©ration est coĂ»teuse en calcul et facturĂ©e en consĂ©quence.Pour lâaudio, vous pouvez ajouter
"mean_volume": truepour obtenir une valeur unique représentant le volume moyen du fichier audio.Vous pouvez également définir cette option sur
falsepour ignorer lâextraction des mĂ©tadonnĂ©es et accĂ©lĂ©rer le transcodage.user_metaRecord<string, any>(par dĂ©faut :{})Ajoute des mĂ©tadonnĂ©es JSON personnalisĂ©es Ă chaque fichier Ă©mis sans modifier son contenu. Les objets et tableaux imbriquĂ©s sont pris en charge.
LâhĂ©ritage dĂ©pend du Robot. Les valeurs sont fusionnĂ©es avec la valeur
user_metaexistante du fichier de sortieâŻ; le Step actuel remplace les clĂ©s de premier niveau correspondantes. Attribuez explicitement les clĂ©s requises lorsquâun Robot crĂ©e de nouvelles sorties.Dans les Steps de traitement,
${file.*}dĂ©signe la premiĂšre entrĂ©e et${result.*}le fichier Ă©mis. Les valeurs sont Ă©valuĂ©es pour chaque sortie aprĂšs lâexĂ©cution du Robot, avant lâextraction ultĂ©rieure des mĂ©tadonnĂ©es et le stockage temporaire. Sur:original, les valeurs sont Ă©valuĂ©es pour chaque tĂ©lĂ©versement avant lâextraction des mĂ©tadonnĂ©es.Les Steps en aval lisent
${file.user_meta.key}. Consultez MĂ©tadonnĂ©es personnalisĂ©es pour un exemple complet et les rĂšgles dâhĂ©ritage.resultboolean(par dĂ©faut :false)Indique si les rĂ©sultats de ce Step doivent figurer dans lâAssembly Status JSON
queuebatchDĂ©finir la file dâattente sur « batch » abaisse manuellement la prioritĂ© des Jobs de ce Step afin dâĂ©viter de consommer des emplacements prioritaires de Jobs pour des Jobs qui nâont pas besoin dâun temps dâattente nul dans la file
force_acceptboolean(par dĂ©faut :false)Forcer un Robot Ă accepter un type de fichier quâil aurait ignorĂ©.
Par dĂ©faut, les Robots ignorent les fichiers quâils ne connaissent pas. Le Robot đ€/video/encode, par exemple, ignorera volontiers les images en entrĂ©e.
Avec le paramĂštre
force_acceptdĂ©fini surtrue, vous pouvez forcer les Robots Ă accepter tous les fichiers qui leur sont envoyĂ©s. Cela entraĂźne gĂ©nĂ©ralement des erreurs et ne doit ĂȘtre utilisĂ© que pour le dĂ©bogage ou pour traiter des cas limites.ignore_errorsboolean | Array<meta | execute>(par dĂ©faut :[])Ignore les erreurs pendant certaines phases du traitement.
Si vous définissez cette valeur sur
["meta"], le Robot ignorera les erreurs lors de lâextraction des mĂ©tadonnĂ©es.Si vous dĂ©finissez cette valeur sur
["execute"], le Robot ignorera les erreurs lors de la phase dâexĂ©cution principale.DĂ©finir cette valeur sur
trueĂ©quivaut Ă["meta", "execute"] : les erreurs seront alors ignorĂ©es dans les deux phases.usestring | Array<string> | Array<object> | objectIndique quel(s) Step(s) utiliser comme entrĂ©e.
- Vous pouvez choisir nâimporte quel nom pour les Steps, sauf
":original"(rĂ©servĂ© aux tĂ©lĂ©versements des utilisateurs gĂ©rĂ©s par Transloadit) - Vous pouvez fournir plusieurs Steps en entrĂ©e Ă lâaide de tableaux :
{ "use": [ ":original", "encoded", "resized" ] } - Vous pouvez Ă©galement Ă©tiqueter les Steps dâentrĂ©e avec
aspour transmettre une intention sémantique aux Robots :{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
AstuceCâest probablement tout ce que vous devez savoir sur
use, mais vous pouvez consulter les cas dâutilisation avancĂ©s.- Vous pouvez choisir nâimporte quel nom pour les Steps, sauf
ffmpegobjectUn objet de paramÚtres à transmettre à FFmpeg. Si un préréglage est utilisé, les options spécifiées sont fusionnées par-dessus celles du préréglage. Pour connaßtre les options disponibles, consultez la documentation de FFmpeg. Les options spécifiées ici ont priorité sur celles du préréglage.
ffmpeg_stackv6 | v7 | v8 | string(par dĂ©faut :"v6.0.0")SĂ©lectionne la version de la pile FFmpeg Ă utiliser pour lâencodage. Nous recommandons actuellement dâutiliser « v7 ». Les versions exactes « v6.0.0 », « v7.0.0 » et « v8.0.0 » sont des valeurs hĂ©ritĂ©es qui restent acceptĂ©es pour assurer la rĂ©trocompatibilitĂ©. Les valeurs « v5.x », dĂ©prĂ©ciĂ©es, sont Ă©galement acceptĂ©es.
countstring | number(par dĂ©faut :8)Le nombre de vignettes Ă extraire. Comme certaines vidĂ©os ont des durĂ©es incorrectes, le nombre rĂ©el de vignettes gĂ©nĂ©rĂ©es peut, dans de rares cas, ĂȘtre infĂ©rieur. Le nombre maximal de vignettes que nous autorisons actuellement est de 999.
Lorsque
smartvautfalse, les vignettes sont prises Ă intervalles rĂ©guliers. Par exemple, une valeur de 3 produit des vignettes Ă 25 %, 50 % et 75 % de la durĂ©e de la vidĂ©o. Avecsmart: true, il sâagit plutĂŽt du nombre de vignettes sĂ©lectionnĂ©es parmi lâensemble des images candidates.Pour extraire des vignettes Ă des horodatages prĂ©cis, utilisez le paramĂštre
offsets.offsetsArray<string | number> | Array<string> | nullUn tableau de décalages représentant des secondes de la durée du fichier, par exemple
[ 2, 45, 120 ]. Des durĂ©es en millisecondes peuvent Ă©galement ĂȘtre utilisĂ©es Ă lâaide de valeurs dĂ©cimales. Par exemple, un dĂ©calage de 1250 millisecondes serait reprĂ©sentĂ© par1.25. Les dĂ©calages peuvent aussi ĂȘtre des valeurs en pourcentage, comme[ "2%", "50%", "75%" ].Lorsque
smartvautfalse,offsetsa prioritĂ© surcount. Demandez des horodatages compris dans la durĂ©e de la vidĂ©o. Si FFmpeg ne produit aucune image Ă un dĂ©calage demandĂ©, le Robot peut rĂ©essayer sans positionnement par horodatage et renvoyer Ă la place une image proche du dĂ©but. Il nâignore pas simplement le dĂ©calage, et lâextraction peut tout de mĂȘme Ă©chouer si aucune image nâest disponible.Lorsque
smartvauttrue, la sĂ©lection intelligente ignoreoffsetset utilisecountpour faire son choix parmi ses propres horodatages candidats. Si aucune image candidate de la sĂ©lection intelligente ne peut ĂȘtre extraite, le Robot revient Ă lâextraction standard, oĂčoffsetsa prioritĂ©. Utilisezsmart: falsepour extraire systĂ©matiquement les horodatages indiquĂ©s.Utilisez
nullpour laissercountetsmartdéterminer la sélection des horodatages.formatjpeg | jpg | png(par défaut :"jpeg")Le format de la vignette extraite. Les valeurs prises en charge sont
"jpg","jpeg"et"png". MĂȘme si vous indiquez le format"jpeg", les vignettes obtenues auront lâextension de fichier"jpg".widthstring | number | nullLa largeur de la vignette, en pixels. Omettez ce paramĂštre ou utilisez
nullpour conserver la largeur dâorigine de la vidĂ©o.heightstring | number | nullLa hauteur de la vignette en pixels, plafonnĂ©e de la mĂȘme maniĂšre que
width. Omettez ce paramĂštre ou utiliseznullpour conserver la hauteur dâorigine.resize_strategycrop | fit | fillcrop | min_fit | pad | stretch(par dĂ©faut :"pad")Lâune des stratĂ©gies de redimensionnement disponibles.
backgroundstring(par dĂ©faut :"#000000ff")La couleur dâarriĂšre-plan des vignettes obtenues, au format
"rrggbbaa"(rouge, vert, bleu, alpha), lorsque ce paramĂštre est utilisĂ© avec la stratĂ©gie de redimensionnement"pad". La couleur par dĂ©faut est le noir opaque.rotate0 | 90 | 180 | 270 | 360(par dĂ©faut :0)Force la rotation de la vidĂ©o selon le nombre entier de degrĂ©s indiquĂ©. Actuellement, seuls les multiples de 90 sont pris en charge. Nous corrigeons automatiquement lâorientation de nombreuses vidĂ©os lorsque celle-ci est fournie par la camĂ©ra. Cette option nâest utile que pour les vidĂ©os nĂ©cessitant une rotation parce que leur orientation nâa pas Ă©tĂ© dĂ©tectĂ©e par la camĂ©ra.
input_codecstringIndique le codec dâentrĂ©e Ă utiliser pour dĂ©coder la vidĂ©o. Cela est utile pour les vidĂ©os dotĂ©es de codecs particuliers qui nĂ©cessitent des dĂ©codeurs spĂ©cifiques.
smartboolean(par dĂ©faut :false)Lorsquâil est dĂ©fini sur
true, ce paramĂštre active la sĂ©lection intelligente de vignettes par IA. Au lieu de renvoyer des vignettes Ă intervalles rĂ©guliers, le Robot analyse les images candidates et sĂ©lectionne les plus attrayantes visuellement.LâIA Ă©value les images selon les critĂšres suivants :
- Netteté visuelle (en évitant les images floues ou sombres)
- Qualité de la composition
- Présence et expressions des visages
- Action et mouvement (en évitant les images de transition)
- IntĂ©rĂȘt visuel global
Les frais de traitement habituels de
/video/thumbssâappliquent toujours. Lâanalyse des images par IA utilise un modĂšle de vision dĂ©diĂ© Ă faible coĂ»t avec le niveau de raisonnementlow, ainsi que des copies dâaperçu limitĂ©es Ă 512 pixels sur le cĂŽtĂ© le plus long. Les vignettes renvoyĂ©es conservent les dimensions et le format demandĂ©s. Lâanalyse est facturĂ©e sĂ©parĂ©ment au coĂ»t du fournisseur sous-jacent, majorĂ© dâune marge Transloadit de 50 %. Vous nâavez pas besoin de fournir dâinformations dâidentification IA.Le mode intelligent gĂ©nĂšre ses propres horodatages candidats rĂ©guliĂšrement espacĂ©sâŻ; utilisez
smart: falseavecoffsetslorsque vous avez besoin dâhorodatages prĂ©cis. Les vignettes intelligentes sĂ©lectionnĂ©es sont renvoyĂ©es dans lâordre chronologique, et non dans lâordre des scores. Examinezmeta.thumb_offset,meta.smart_scoreetmeta.smart_reasonslorsque vous Ă©valuez la sĂ©lection.Si lâĂ©valuation par IA Ă©choue, le Robot sĂ©lectionne les images candidates extraites dans lâordre chronologique et enregistre un motif de repli. En lâabsence dâimages candidates, il tente une extraction standard. Ces deux replis ajoutent un avertissement Ă lâAssembly. Une Assembly terminĂ©e ne garantit pas une image dâaffiche reprĂ©sentative ou adaptĂ©e Ă la publicationâŻ; vĂ©rifiez que les rĂ©sultats existent et appliquez la politique de vĂ©rification de votre application.
smart_max_candidatesstring | number(par dĂ©faut :20)La taille maximale de lâensemble des images candidates lorsque
smartvauttrue. Le Robot analyse jusquâĂ trois images candidates par vignette demandĂ©e, dans la limite de cette valeur, mais il nâanalysera jamais moins dâimages candidates que la valeurcountdemandĂ©e.Un nombre plus Ă©levĂ© peut donner de meilleurs rĂ©sultats, mais augmente le temps de traitement et le coĂ»t de lâIA. Avec les valeurs par dĂ©faut
count: 8etsmart_max_candidates: 20, le Robot analyse 20 images et renvoie les 8 meilleures dans lâordre chronologique.Relever cette limite au-delĂ de trois fois
countnâĂ©largit pas lâensemble des images candidates. Par exemple, aveccount: 1, le Robot analyse au plus trois images candidates.Ce paramĂštre nâest utilisĂ© que lorsque
smartvauttrue.
Démonstrations
Articles de blog associés
- AmĂ©liorer FFmpeg pour des performances dâencodage supĂ©rieures
- Intégration Zapier de Transloadit
- Nouveau modĂšle tarifaire pour les futurs clients de Transloadit
- Découverte du Robot /google/store dans la série Re-Loadit
- Guide dâencodage de vidĂ©os pour le streaming avec Transloadit
- Migrer depuis Cloudinary, Filestack, Mux ou Uploadcare
- Let AI pick your video thumbnails (English)