SDK pour Node.js
Nous proposons un kit de développement complet pour Node.js afin de faciliter les échanges avec l’API REST de Transloadit depuis vos applications Node.
Installer
Le SDK actuel est exclusivement ESM et prend en charge Node.js 20.10.0 ou une version ultérieure. Les exemples Storage ci-dessous utilisent le SDK et la CLI en version 6.9.0 ou ultérieure. Pour les anciennes documentations, consultez la v3 ou la v2. Pour les détails de mise à niveau, consultez le guide de migration.
Utilisez @transloadit/node comme nom de paquet. L’ancien nom de paquet npm
transloadit est conservé comme alias pour assurer la rétrocompatibilité.
Dans votre projet, installez le SDK avec npm :
npm install @transloadit/node
Si votre projet utilise déjà Yarn ou pnpm, conservez plutôt son gestionnaire de paquets et son fichier de verrouillage :
yarn add @transloadit/node
Pour pnpm, utilisez pnpm add @transloadit/node.
CLI
Ce paquet inclut une CLI complète :
npx @transloadit/node --help
npx @transloadit/node auth login
La connexion ouvre le navigateur pour vous permettre de choisir un Workspace et d’autoriser la CLI sans copier de secret d’API dans votre shell. Pour l’automatisation et les serveurs d’applications, utilisez des Auth Keys configurées séparément ; la référence des informations d’identification décrit les options prises en charge. Ne déployez pas la clé de connexion jetable de la CLI comme clé d’application.
npx @transloadit/node utilise la CLI de votre SDK installé, ou propose de la récupérer si
le paquet est absent. Les exemples nomment explicitement le paquet ; aucune installation globale
n’est nécessaire. Pour une démonstration autonome de Storage, utilisez
l’initialiseur upload-once maintenu.
Commandes Intent
Pour les tâches ponctuelles rapides, la CLI propose aussi des commandes Intent de haut niveau. Elles regroupent des flux de travail Transloadit courants derrière des sous-commandes intuitives, pour vous éviter de commencer chaque tâche par des Assembly Instructions en JSON.
Si vous exportez une Auth Key au lieu d’utiliser la connexion par navigateur, utilisez l’algorithme
de signature correspondant. L’exemple CLI avec clé manuelle et les exemples JavaScript ci-dessous
utilisent SHA-256, qu’acceptent les Auth Keys pour lesquelles la signature Smart CDN est activée.
Si votre clé utilise un autre algorithme, comme SHA-384 pour les clés sans signature Smart CDN,
définissez la valeur correspondante dans TRANSLOADIT_SIGNATURE_ALGORITHM et
signatureAlgorithm.
Par exemple :
export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
export TRANSLOADIT_SIGNATURE_ALGORITHM="sha256"
npx @transloadit/node markdown pdf --input ./README.md --print-urls
Voici d’autres exemples :
npx @transloadit/node image remove-background --input ./photo.jpg --print-urlsnpx @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.pngnpx @transloadit/node image generate --input ./person1.jpg --input ./person2.jpg --input ./background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --output scene.pngnpx @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
image generate utilise désormais google/nano-banana-2 par défaut,
y compris pour les exécutions guidées par les données d’entrée.
Si vous omettez --output, la CLI écrit si possible à côté du fichier local
fourni en entrée lorsqu’il est unique. Sinon, elle utilise le répertoire de travail courant.
Utilisez --print-urls seul pour obtenir des URL de résultats temporaires sans
téléchargement local.
Nous avons également mis à jour le dépôt public des Skills Transloadit pour utiliser le même flux de génération d’images fondé sur Intent.
Pour la référence complète des commandes, consultez la référence des commandes Intent et le README du paquet.
Storage et diffusion d’images
Essayez Storage et le Smart CDN avec l’exemple upload-once, ou suivez le guide Viewer pour Next.js pour afficher des images adaptatives dans une application existante.
La CLI peut stocker des originaux de différents types de médias, pas seulement des images :
npx @transloadit/node storage store ./photo.jpg ./clip.mp4 ./guide.pdf website/media/
Cela ne publie pas le répertoire. Utilisez storeAsset() pour les téléversements
depuis un serveur d’applications et conservez le reçu de ressource/version renvoyé avec son
propriétaire. Consultez les
originaux de différents types de médias
pour la vérification des octets, l’écrasement explicite, la récupération du catalogue et le
téléchargement des originaux. Les sources HTTP/S3 existantes peuvent aussi utiliser Viewer sans
migrer vers Storage.
Projets CommonJS
Le SDK est exclusivement ESM. Si vous utilisez CommonJS, utilisez un import dynamique :
async function getClient() {
const { Transloadit } = await import('@transloadit/node')
return new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
}
Utilisation
Le code suivant téléverse une image et la redimensionne en vignette :
import { ApiError, Transloadit } from '@transloadit/node'
const transloadit = new Transloadit({
authKey: 'YOUR_TRANSLOADIT_KEY',
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
try {
const options = {
files: {
file1: '/PATH/TO/FILE.jpg',
},
params: {
steps: {
// You can have many Steps. In this case we will just resize any inputs (:original)
resize: {
use: ':original',
robot: '/image/resize',
result: true,
width: 75,
height: 75,
},
},
// OR if you already created a template, you can use it instead of "steps":
// template_id: 'YOUR_TEMPLATE_ID',
},
waitForCompletion: true, // Wait for the Assembly (job) to finish executing before returning
}
const status = await transloadit.createAssembly(options)
if (status.results.resize) {
console.log('✅ Success - Your resized image:', status.results.resize[0].ssl_url)
} else {
console.log("❌ The Assembly didn't produce any output. Make sure you used a valid image file")
process.exitCode = 1
}
} catch (err) {
console.error('❌ Unable to process Assembly:', err instanceof ApiError ? (err.code ?? 'API request failed.') : 'Check your connection and input files.')
process.exitCode = 1
if (err instanceof ApiError && err.assemblyId) {
console.error(`💡 More info: https://api2.transloadit.com/assemblies/${err.assemblyId}`)
}
}
Vous trouverez ici les détails de vos Assemblies exécutées.
Exemples
- Téléverser et redimensionner une image
- Téléverser une image et la convertir en WebP
- Rastériser un SVG en PNG
- Recadrer une image autour d’un visage et télécharger le résultat
- Exemple de nouvelle tentative
- Calculer les coûts totaux (utilisation en GB)
- Opérations CRUD sur les Templates
- Opérations CRUD sur les ensembles d’informations d’identification de Template
Pour d’autres exemples entièrement fonctionnels, consultez
examples/.
Documentation
Consultez GitHub pour la documentation complète et le guide de migration pour les détails de mise à niveau.