Von null zur verarbeiteten Datei mit der Transloadit CLI

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Verarbeiten Sie eine Datei im Terminal, ohne API-Secrets zu kopieren. Führen Sie auth login aus, genehmigen Sie die Anfrage im Browser (oder registrieren Sie sich dort zuerst), und Ihr nächster Befehl verarbeitet eine Datei.

Dieselbe CLI kann einen Satz in Assembly Instructions umwandeln, handgeschriebene Instructions auf Fehler prüfen und korrigieren und sie auf einen ganzen Ordner anwenden. Im Folgenden zeigen wir all das mit unserer Produktions-API sowie die Lösung des Node-SDK für Uploads, die auf halbem Weg abbrechen.

Im Browser anmelden

Die folgenden Beispiele verwenden @transloadit/node 5.1.0. Die CLI-Befehle laufen mit npx, Sie benötigen also nur Node.js 20.10 oder neuer:

$ npx -y @transloadit/node auth login
Enter code VKVQ-C5H6 at https://transloadit.com/c/cli-auth?code=VKVQ-C5H6

Die CLI öffnet diese Seite für Sie. Mit --no-browser gibt sie nur den Link aus, was bei SSH-Verbindungen hilfreich ist. Melden Sie sich an oder registrieren Sie sich, wenn Sie noch kein Konto haben. Prüfen Sie, ob der Code auf der Seite mit dem im Terminal übereinstimmt, und genehmigen Sie die Anfrage. Die CLI gibt dann Logged in to workspace … aus, und Sie können loslegen. Die Codes laufen nach 15 Minuten ab.

Die Genehmigung erstellt einen neuen Auth Key in Ihrem Workspace. Er wird mit dem Hostnamen Ihres Rechners und dem Datum beschriftet, damit Sie ihn später unter Zugangsdaten in der Console finden. Die CLI speichert ihn in ~/.transloadit/credentials, einer Datei, die nur Ihr Benutzer lesen kann. Dieser eine Schlüssel kann Assemblies erstellen, Templates lesen und Smart CDN-URLs signieren. auth status zeigt, in welchem Workspace Sie angemeldet sind, und auth logout löscht die Datei und widerruft den Schlüssel. Sie haben bereits einen Schlüssel? auth login --stdin importiert ihn stattdessen aus einer Eingabe im dotenv-Stil.

Ihre Anmeldung auf dem Laptop ist nicht für die Automatisierung gedacht:

• Übergeben Sie in CI weiterhin TRANSLOADIT_KEY und TRANSLOADIT_SECRET aus Ihrer Zugangsdatenverwaltung. Verwenden Sie dabei einen Schlüssel, dessen Scope auf den jeweiligen CI-Job begrenzt ist. Umgebungsvariablen haben Vorrang vor der gespeicherten Anmeldung.
• Verwenden Sie auf Anwendungsservern einen separaten Deployment-Schlüssel, damit eine Abmeldung auf Ihrem Laptop niemals den Produktionsbetrieb beeinträchtigt.

Von einem Satz zur verarbeiteten Datei

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 kompiliert Ihren Satz zu Assembly Instructions, prüft das Ergebnis mit den unten beschriebenen Lint-Prüfungen und unternimmt bis zu drei Versuche, wenn dabei Fehler gefunden werden. Anschließend führt es die Instructions für Ihre Datei aus. Unser JPEG mit 9,3 MB kam als WebP mit 62 KB zurück, nach etwa 20 Sekunden inklusive Kompilierung.

Die Kompilierung ist selbst eine Assembly, die den Robot 🤖 /ai/chat EN (English) verwendet. Sie erscheint daher wie jede andere Assembly in Ihrer Nutzung. Wenn Sie dieselbe Aufgabe erneut benötigen, kompilieren Sie einmal und bewahren Sie die Ausgabe auf:

npx -y @transloadit/node assembly-instructions compile "resize to 400px wide and convert to WebP" > webp-thumbs.json

Die generierten Instructions können so aussehen:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "webp": {
      "robot": "/image/resize",
      "use": ":original",
      "width": 400,
      "resize_strategy": "fit",
      "zoom": true,
      "format": "webp",
      "background": "none",
      "result": true
    }
  }
}

Das ist für den Robot 🤖 /image/resize ein einzelner Step, den Sie prüfen, committen und wiederverwenden können, ohne erneut ein Modell aufzurufen. Ein Modell kann für denselben Satz unterschiedliche Instructions liefern. Lesen Sie also, was Sie aufbewahren. Für gängige Aufgaben mit festen Flags und ohne KI bleiben die Intent-Befehle wie image resize der schnellere Weg.

Übergeben Sie die gespeicherte Datei direkt an assemblies create, um sie wiederzuverwenden:

npx -y @transloadit/node assemblies create --steps webp-thumbs.json -i chameleon.jpg -o saved-thumb.webp

Fehler vor dem Produktionseinsatz erkennen

assemblies lint prüft Instructions auf Ihrem Rechner mit demselben Linter, den unser Console-Editor und MCP-Server verwenden. Dafür sind keine Zugangsdaten nötig. So läuft die Prüfung in CI und Pre-Commit-Hooks ohne Secrets. Hier ist eine Datei mit drei häufigen Fehlern: einem Step ohne use, einem doppelten JSON-Parameterschlüssel und einem Tippfehler in einem Step-Namen.

{
  "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 …

Fügen Sie --fix hinzu. Dann korrigiert der Linter, was er sicher korrigieren kann, und überschreibt die Datei direkt:

$ 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 …

Der Step thumb lautet jetzt:

{
  "steps": {
    // …
    "thumb": {
      "robot": "/image/resize",
      "width": 800,
      "height": 300,
      "use": ":original"
    },
    // …
  },
}

--fix hat den letzten Wert für width behalten, also den Wert, den auch ein JSON-Parser beibehält, den Step auf :original ausgerichtet und die Datei neu formatiert. Der Tippfehler bleibt, weil der Linter nicht wissen kann, welchen Step Sie meinten. Ändern Sie thumbs in thumb. Dann besteht die Datei die Prüfung, selbst wenn Warnungen als Fehler behandelt werden:

$ npx -y @transloadit/node assemblies lint --steps steps.json --fatal warning
No issues found

Bei Fehlern beendet sich der Linter mit einem Exit-Code ungleich null, mit --fatal warning auch bei Warnungen. Derselbe Befehl in einem CI-Lauf stoppt somit fehlerhafte Instructions, bevor sie ausgeliefert werden. --steps - liest von stdin, --json gibt Probleme maschinenlesbar aus, und --template prüft Ihre Steps nach dem Zusammenführen mit einem gespeicherten Template, genau wie die API sie zusammenführt. Für diese letzte Option sind Zugangsdaten nötig.

Einen ganzen Ordner verarbeiten

assemblies create führt Instructions für Dateien und Verzeichnisse aus und lädt die Ergebnisse herunter. --steps akzeptiert sowohl die folgende Datei, die nur Steps enthält, als auch die oben gezeigte Form { "steps": … }. Mit einigen JPEGs in photos/ entstehen so 400 Pixel breite Thumbnails:

{
  ":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/

Jedes Foto erhält eine eigene Assembly, standardmäßig fünf gleichzeitig (--concurrency ändert das). Jedes Ergebnis wird unter dem Dateinamen des Fotos in thumbs/ gespeichert. Wenn Sie den Befehl erneut ausführen, überspringt er jedes Foto, dessen Thumbnail neuer als das Original ist. So fällt nur für neue oder geänderte Dateien eine Assembly an. --reprocess-stale verarbeitet alles erneut. Fügen Sie --recursive für Unterordner hinzu oder --watch, damit der Befehl weiterläuft und Dateien verarbeitet, sobald sie sich ändern.

Uploads nach einem Absturz fortsetzen

Für große Uploads aus Ihren eigenen Node.js-Skripten setzt die SDK-Methode resumeAssemblyUploads() einen unterbrochenen Upload fort, statt von vorn zu beginnen. Installieren Sie @transloadit/node@5.1.0 in Ihrem Projekt und setzen Sie TRANSLOADIT_KEY und TRANSLOADIT_SECRET für einen Anwendungs-Auth Key, der für SHA-384 konfiguriert ist, den Standard des SDK. Diese Skripte lesen Zugangsdaten aus Umgebungsvariablen. Laden Sie das Beispielfoto herunter:

curl -fsSLo prinsengracht.jpg https://demos.transloadit.com/inputs/prinsengracht.jpg

Speichern Sie die Assembly URL, sobald der Upload beginnt:

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

Wenn dieser Prozess abbricht, sendet ein zweites Skript die fehlenden Bytes in dieselbe 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)

Wir haben den Upload eines 14 MB großen Fotos mit dem Signal unterbrochen, das Ctrl+C sendet, den teilweisen Upload im Status der Assembly bestätigt und ihn fortgesetzt:

$ node upload.mjs
^C
$ node resume.mjs
1048576 bytes uploaded
1114112 bytes uploaded
…
14160569 bytes uploaded
ASSEMBLY_COMPLETED

Der Upload wurde bei 1.048.576 Bytes statt bei null fortgesetzt. Das SDK ordnet Uploads anhand von Feldname, Dateiname und Größe zu. Übergeben Sie daher dieselben Pfade wie zuvor. Nur Eingaben über Dateipfade lassen sich fortsetzen, Streams oder Puffer hingegen nicht. Die API aktualisiert den Status teilweiser Uploads asynchron. Wenn Sie den Upload fortsetzen, bevor der teilweise Upload im Status der Assembly erscheint, lädt das SDK diese Datei erneut von Anfang an hoch, weiterhin in dieselbe Assembly.

Grenzen kennen

• Der Schlüssel aus der Browser-Anmeldung kann Assemblies ausführen und Templates lesen, aber keine Templates erstellen oder ändern. Schreibende Befehle von templates benötigen einen separaten Schlüssel mit dieser Berechtigung.
• run und compile verwenden ein KI-Modell. Zwei Ausführungen desselben Satzes können unterschiedliche Instructions erzeugen.
• Im kostenlosen Community-Tarif erhalten Bildergebnisse ein Wasserzeichen, und Audio- und Videoergebnisse werden gekürzt. Unsere FAQ erklärt, warum.

Ausprobieren

npx -y @transloadit/node auth login

Sie haben noch kein Konto? Registrieren Sie sich auf der Seite, die sich öffnet, oder erstellen Sie zuerst ein Konto. Die CLI-Übersicht stellt das Tool vor, und die SDK-README⁠ dokumentiert die Befehle und die API zum Fortsetzen von Uploads. Wenn Sie Transloadit lieber von einem Agenten steuern lassen möchten, sehen Sie sich unseren MCP-Server und unsere Agenten-Skills an. Teilen Sie uns im Issue-Tracker von node-sdk⁠ mit, was fehlt.