Node.js-SDK
Unser voll ausgestattetes Software Development Kit für Node.js vereinfacht den Zugriff auf die Transloadit REST API aus Ihren Node-Apps.
Installation
Das aktuelle SDK unterstützt ausschließlich ESM und Node.js ab Version 20.10.0. Die folgenden Storage-Beispiele verwenden SDK/CLI ab Version 6.9.0. Ältere Dokumentation finden Sie unter v3 oder v2. Details zum Upgrade stehen im Migrationsleitfaden.
Verwenden Sie @transloadit/node als Paketnamen. Der bisherige npm-Paketname
transloadit bleibt als Alias zur Abwärtskompatibilität erhalten.
Installieren Sie das SDK in Ihrem Projekt mit npm:
npm install @transloadit/node
Wenn Ihr Projekt bereits Yarn oder pnpm nutzt, behalten Sie stattdessen dessen Paketmanager und Lockdatei bei:
yarn add @transloadit/node
Für pnpm verwenden Sie pnpm add @transloadit/node.
CLI
Dieses Paket enthält eine voll ausgestattete CLI:
npx @transloadit/node --help
npx @transloadit/node auth login
Die Anmeldung öffnet den Browser, damit Sie einen Workspace auswählen und die CLI autorisieren können, ohne ein API-Secret in Ihre Shell zu kopieren. Für Automatisierung und Anwendungsserver verwenden Sie separat konfigurierte Auth Keys; die Referenz zu Zugangsdaten beschreibt die unterstützten Optionen. Verwenden Sie den kurzlebigen CLI-Anmeldeschlüssel nicht als Anwendungsschlüssel.
npx @transloadit/node verwendet die CLI aus Ihrem installierten SDK oder bietet an,
sie herunterzuladen, wenn das Paket fehlt. Die Beispiele nennen das Paket explizit;
eine globale Installation ist nicht erforderlich.
Für eine eigenständige Storage-Demo verwenden Sie den gepflegten
upload-once-Initializer.
Intent-Befehle
Für schnelle einmalige Aufgaben enthält die CLI auch übergeordnete Intent-Befehle. Sie bündeln häufige Transloadit-Workflows in leicht erschließbaren Unterbefehlen, sodass Sie nicht für jede Aufgabe mit Assembly Instructions in JSON beginnen müssen.
Wenn Sie einen Auth Key exportieren, statt die Browser-Anmeldung zu nutzen, verwenden Sie den
passenden Signaturalgorithmus. Das CLI-Beispiel mit manuellem Schlüssel und die folgenden
JavaScript-Beispiele nutzen SHA-256. Auth Keys mit aktivierter Smart-CDN-Signierung akzeptieren
diesen Algorithmus. Nutzt Ihr Schlüssel einen anderen Algorithmus, etwa SHA-384 bei Schlüsseln
ohne Smart-CDN-Signierung, setzen Sie den passenden Wert in TRANSLOADIT_SIGNATURE_ALGORITHM
und signatureAlgorithm.
Zum Beispiel:
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
Weitere Beispiele:
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 verwendet jetzt standardmäßig google/nano-banana-2,
auch bei eingabegesteuerten Ausführungen.
Wenn Sie --output weglassen, schreibt die CLI nach Möglichkeit neben die
Eingabedatei, sofern diese eine einzelne lokale Datei ist. Andernfalls nutzt sie das aktuelle
Arbeitsverzeichnis. Verwenden Sie --print-urls allein, wenn Sie temporäre
Ergebnis-URLs ohne lokalen Download wünschen.
Wir haben auch das öffentliche Transloadit-Skills-Repository aktualisiert, damit es denselben Intent-basierten Ablauf zur Bilderzeugung nutzt.
Die vollständige Befehlsreferenz finden Sie in der Referenz der Intent-Befehle und in der README des Pakets.
Storage und Bildauslieferung
Testen Sie Storage und das Smart CDN mit dem upload-once-Beispiel, oder folgen Sie der Anleitung zum Viewer für Next.js, um responsive Bilder in einer bestehenden App darzustellen.
Die CLI kann Originale verschiedener Medientypen speichern, nicht nur Bilder:
npx @transloadit/node storage store ./photo.jpg ./clip.mp4 ./guide.pdf website/media/
Dadurch wird das Verzeichnis nicht veröffentlicht. Verwenden Sie storeAsset()
für Uploads vom Anwendungsserver und speichern Sie den zurückgegebenen Asset-/Versionsbeleg
zusammen mit der Eigentümerzuordnung. Informationen zur Byte-Verifizierung, zum expliziten
Überschreiben, zur Katalogwiederherstellung und zum Download der Originale finden Sie unter
Originale verschiedener Medientypen. Bestehende HTTP-/S3-Quellen
können Viewer auch ohne Migration zu Storage nutzen.
CommonJS-Projekte
Das SDK unterstützt ausschließlich ESM. Wenn Sie CommonJS nutzen, verwenden Sie einen dynamischen Import:
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',
})
}
Verwendung
Der folgende Code lädt ein Bild hoch und verkleinert es zu einem Thumbnail:
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}`)
}
}
Details zu Ihren ausgeführten Assemblies finden Sie hier.
Beispiele
- Bild hochladen und Größe ändern
- Bild hochladen und in WebP konvertieren
- SVG als PNG rastern
- Gesicht aus einem Bild ausschneiden und Ergebnis herunterladen
- Beispiel für erneute Versuche
- Gesamtkosten berechnen (GB-Nutzung)
- CRUD für Templates
- CRUD für Template-Zugangsdaten
Weitere voll funktionsfähige Beispiele finden Sie unter
examples/.
Dokumentation
Die vollständige Dokumentation finden Sie auf GitHub, Details zum Upgrade im Migrationsleitfaden.