De zéro à un fichier traité avec la CLI Transloadit
Traitez un fichier depuis votre terminal sans copier de secrets d’API. Exécutez
auth login, approuvez la demande dans votre navigateur (ou inscrivez-vous
préalablement sur cette page), et votre prochaine commande traitera un fichier.
La même CLI peut transformer une phrase en Assembly Instructions, analyser et corriger les Instructions que vous avez rédigées à la main, puis les exécuter sur un dossier entier. Nous allons examiner chacune de ces possibilités avec notre API de production, ainsi que la solution du SDK Node pour les téléversements interrompus à mi-parcours.
Se connecter depuis le navigateur
Les exemples ci-dessous utilisent @transloadit/node 5.1.0. Les commandes de la CLI passent
par npx : il vous suffit donc de disposer de Node.js 20.10 ou d’une version
plus récente :
$ npx -y @transloadit/node auth login
Enter code VKVQ-C5H6 at https://transloadit.com/c/cli-auth?code=VKVQ-C5H6
La CLI ouvre cette page pour vous. Avec --no-browser, elle affiche uniquement le
lien, ce qui est utile via SSH. Connectez-vous, ou inscrivez-vous si vous n’avez pas encore de compte,
vérifiez que le code de la page correspond à celui de votre terminal, puis approuvez la demande.
La CLI affiche alors Logged in to workspace … et vous pouvez commencer. Les codes expirent
après 15 minutes.
L’approbation crée une nouvelle Auth Key dans votre
Workspace, avec un libellé indiquant le nom d’hôte de
votre machine et la date, afin que vous puissiez la retrouver ensuite sous Informations d’identification
dans la Console. La CLI la stocke dans ~/.transloadit/credentials, un fichier que seul votre
utilisateur peut lire. Cette seule clé permet de créer des
Assemblies, de lire des
Templates et de signer des URL du
Smart CDN. auth status indique à quel Workspace
vous êtes connecté, et auth logout supprime le fichier et révoque la clé. Vous avez
déjà une clé ? auth login --stdin permet plutôt de l’importer à partir d’une entrée au
format dotenv.
La connexion enregistrée sur votre ordinateur portable n’est pas destinée à l’automatisation :
- En CI, continuez à fournir
TRANSLOADIT_KEYetTRANSLOADIT_SECRETdepuis votre gestionnaire de secrets, avec une clé dont le périmètre d’autorisation est limité à cette tâche. Les variables d’environnement ont priorité sur la connexion enregistrée. - Sur les serveurs d’application, utilisez une clé de déploiement distincte, afin qu’une déconnexion sur votre ordinateur portable ne perturbe jamais la production.
Transformer une phrase en fichier traité
curl -fsSLo chameleon.jpg https://demos.transloadit.com/inputs/chameleon.jpg
npx -y @transloadit/node run "resize to 400px wide and convert to WebP" -i chameleon.jpg -o chameleon.webp
$ file chameleon.webp
chameleon.webp: RIFF (little-endian) data, WebP image, XMP metadata, EXIF metadata, ICC profile, 400x266
run compile votre phrase en Assembly Instructions, analyse le résultat
avec les vérifications décrites ci-dessous, effectue jusqu’à trois tentatives si l’analyse détecte
des erreurs, puis exécute les Instructions sur votre fichier. Notre JPEG de 9,3 MB a été transformé
en WebP de 62 KB en environ 20 secondes, compilation comprise.
La compilation est elle-même une Assembly qui utilise le Robot 🤖 /ai/chat (English) : elle apparaît donc dans votre consommation comme toute autre Assembly. Si vous devez effectuer à nouveau la même tâche, compilez une seule fois et conservez le résultat :
npx -y @transloadit/node assembly-instructions compile "resize to 400px wide and convert to WebP" > webp-thumbs.json
Les Instructions générées peuvent ressembler à ceci :
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"webp": {
"robot": "/image/resize",
"use": ":original",
"width": 400,
"resize_strategy": "fit",
"zoom": true,
"format": "webp",
"background": "none",
"result": true
}
}
}
Ces Instructions générées utilisent le Robot
🤖 /image/resize dans un seul
Step. Vous pouvez les examiner, les enregistrer dans un
commit et les réutiliser sans appeler à nouveau un modèle. Un modèle peut renvoyer des Instructions
différentes pour une même phrase : lisez donc ce que vous conservez. Pour les tâches courantes avec
des options fixes et sans IA, les commandes d’intention (English), comme
image resize, restent plus rapides que la compilation et l’exécution via l’IA.
Passez directement le fichier enregistré à assemblies create pour le réutiliser :
npx -y @transloadit/node assemblies create --steps webp-thumbs.json -i chameleon.jpg -o saved-thumb.webp
Détecter les erreurs avant la production
assemblies lint vérifie les Instructions sur votre machine avec l’outil d’analyse statique commun
à notre éditeur Console et à notre serveur MCP. Aucune information d’accès n’est nécessaire :
il peut donc s’exécuter en CI et dans les hooks de pré-commit sans secrets. Voici un fichier contenant
trois erreurs courantes : un Step sans use, une clé de propriété JSON
en double et une faute de frappe dans le nom d’un Step.
{
"steps": {
":original": { "robot": "/upload/handle" },
"thumb": {
"robot": "/image/resize",
"width": 400,
"height": 300,
"width": 800
},
"optimized": { "robot": "/image/optimize", "use": "thumbs" },
"exported": {
"robot": "/s3/store",
"use": [":original", "thumb", "optimized"],
"credentials": "my-s3-credentials"
}
}
}
$ npx -y @transloadit/node assemblies lint --steps steps.json
[warning] missing-use (3:13) thumb The `use` parameter defines which files a _Robot_ should process. …
[warning] duplicate-key-in-step (7:6) thumb Duplicate key 'width' found
[error] undefined-step (9:54) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …
Ajoutez --fix : l’outil d’analyse statique corrige ce qu’il peut sans risque et réécrit
le fichier sur place :
$ npx -y @transloadit/node assemblies lint --steps steps.json --fix
[error] undefined-step (13:13) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …
Le Step thumb contient désormais :
{
"steps": {
// …
"thumb": {
"robot": "/image/resize",
"width": 800,
"height": 300,
"use": ":original"
},
// …
},
}
--fix a conservé le dernier width, soit la valeur
que conserve un analyseur JSON, a fait pointer le Step vers :original et a
reformaté le fichier. La faute de frappe reste, car l’outil d’analyse statique ne peut pas savoir quel Step vous
vouliez désigner. Remplacez thumbs par thumb : le
fichier passe alors la vérification, même lorsque les avertissements sont traités comme des échecs :
$ npx -y @transloadit/node assemblies lint --steps steps.json --fatal warning
No issues found
L’analyse se termine avec un code de sortie non nul en cas d’erreur et, avec
--fatal warning, en cas d’avertissement également. La même commande dans une tâche CI
bloque donc les Instructions incorrectes avant leur livraison. --steps - lit
l’entrée standard, --json affiche les problèmes dans un format exploitable
par une machine, et --template analyse vos Steps après leur fusion avec un Template
enregistré, comme le fait l’API. Cette dernière option nécessite des informations d’accès.
Traiter un dossier entier
assemblies create exécute les Instructions sur des fichiers et des répertoires, puis
télécharge les résultats. --steps accepte aussi bien le fichier contenant
uniquement des Steps ci-dessous que la forme { "steps": … } présentée plus haut.
Avec quelques JPEG dans photos/, cette commande crée des miniatures de
400 pixels de large :
{
":original": { "robot": "/upload/handle" },
"thumb": { "robot": "/image/resize", "use": ":original", "width": 400 }
}
mkdir -p thumbs
npx -y @transloadit/node assemblies create --steps thumbs.json --input photos/ --output thumbs/
Chaque photo reçoit sa propre Assembly, à raison de cinq simultanément par défaut
(--concurrency modifie ce nombre), et chaque résultat est enregistré dans
thumbs/ sous le nom de fichier de la photo. Si vous relancez la commande, elle
ignore chaque photo dont la miniature est plus récente que l’original. Seuls les fichiers nouveaux
ou modifiés vous coûtent donc une Assembly. --reprocess-stale traite tout à nouveau.
Ajoutez --recursive pour inclure les sous-dossiers, ou
--watch pour laisser la commande active et traiter les fichiers à mesure
qu’ils changent.
Reprendre les téléversements après un plantage
Pour les téléversements volumineux depuis vos propres scripts Node.js, la méthode
resumeAssemblyUploads() du SDK poursuit un téléversement interrompu au lieu de recommencer.
Installez @transloadit/node@5.1.0 dans votre projet et définissez
TRANSLOADIT_KEY et TRANSLOADIT_SECRET pour une Auth Key d’application
configurée pour SHA-384, la valeur par défaut du SDK. Ces scripts lisent les informations d’accès
dans les variables d’environnement. Téléchargez la photo d’exemple :
curl -fsSLo prinsengracht.jpg https://demos.transloadit.com/inputs/prinsengracht.jpg
Enregistrez l’URL de l’Assembly dès le début du téléversement :
import { writeFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
})
const upload = client.createAssembly({
params: { steps: { thumb: { robot: '/image/resize', use: ':original', width: 400 } } },
files: { photo: './prinsengracht.jpg' },
chunkSize: 1024 * 1024,
})
// The Assembly ID exists before the first byte is sent, so save it right away.
await writeFile('assembly.txt', `https://api2.transloadit.com/assemblies/${upload.assemblyId}`)
await upload
Si ce processus s’arrête, un second script envoie les octets manquants dans la même Assembly :
import { readFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
})
const status = await client.resumeAssemblyUploads({
assemblyUrl: await readFile('assembly.txt', 'utf8'),
files: { photo: './prinsengracht.jpg' },
chunkSize: 1024 * 1024,
waitForCompletion: true,
onUploadProgress: ({ uploadedBytes }) => console.log(`${uploadedBytes} bytes uploaded`),
})
console.log(status.ok)
Nous avons interrompu le téléversement d’une photo de 14 MB avec le signal envoyé par Ctrl+C, confirmé le téléversement partiel dans l’état de l’Assembly, puis repris le transfert :
$ node upload.mjs
^C
$ node resume.mjs
1048576 bytes uploaded
1114112 bytes uploaded
…
14160569 bytes uploaded
ASSEMBLY_COMPLETED
Le téléversement a repris à 1 048 576 octets plutôt qu’à zéro. Le SDK associe les téléversements par nom de champ, nom de fichier et taille : fournissez donc les mêmes chemins qu’auparavant. Seules les entrées sous forme de chemins de fichiers permettent la reprise, pas les flux ni les buffers. L’API met à jour l’état du téléversement partiel de manière asynchrone. Si vous reprenez le transfert avant que le téléversement partiel apparaisse dans l’état de l’Assembly, le SDK téléverse à nouveau ce fichier depuis le début, toujours dans la même Assembly.
Connaître les limites
- La clé créée lors de la connexion par navigateur peut exécuter des Assemblies et lire des
Templates, mais elle ne peut ni créer ni modifier de Templates. Les commandes
templatesqui effectuent des écritures nécessitent une clé distincte disposant de cette autorisation. runetcompileutilisent un modèle d’IA, et deux exécutions de la même phrase peuvent produire des Instructions différentes.- Avec le forfait gratuit Community, les images obtenues portent un filigrane, et les résultats audio et vidéo sont raccourcis. Notre FAQ explique pourquoi.
Essayer
npx -y @transloadit/node auth login
Vous n’avez pas encore de compte ? Inscrivez-vous sur la page qui s’ouvre, ou créez d’abord un compte. La présentation de la CLI (English) décrit l’outil, et le README du SDK documente les commandes et l’API de reprise des téléversements. Si vous préférez qu’un agent pilote Transloadit, consultez notre serveur MCP (English) et nos Skills pour agents. Dites-nous ce qui manque dans le suivi des tickets de node-sdk.