@transloadit/node 6.2.1 → 6.3.0

package/src/alphalib/types/robots/_html-pdf.ts

@@ -0,0 +1,3 @@
+/** Shared English contract for the HTML-to-PDF capture used by both conversion Robots. */
+export const htmlPdfReadinessDescription =
+  'For HTML-to-PDF output, printing starts once sampled visible frames, their documents, and their fonts have stayed ready for 500 ms. After navigation, PDF readiness has a 30-second cap; a page that does not become ready fails conversion. Hidden frames do not extend the ready interval. Content that first appears during the final sample window may be missed. Prepare dynamic content before capture.'

package/src/alphalib/types/robots/_video-generate-description.ts

@@ -0,0 +1,2 @@
+/** Scheduled end of the compatibility window for ignored video settings. */
+export const videoGenerationParameterEnforcementDate = '2026-11-16'

package/src/alphalib/types/robots/cloudflare-store.ts

@@ -24,6 +24,20 @@ export const meta: RobotMetaInput = {
     'Export uploaded files to `my_target_folder` in a Cloudflare R2 bucket:',
   extended_description: `
 The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.
+
+## Temporary credentials and permissions
+
+You can use [temporary R2 credentials](https://developers.cloudflare.com/r2/api/s3/temporary-credentials/) by supplying the matching temporary \`key\`, \`secret\`, and \`session_token\`. Use the temporary secret returned or derived with the token, not the parent secret used to mint it. These values can also be stored together in Cloudflare <dfn>Template Credentials</dfn>. For per-Assembly credentials, send all three from your trusted backend; do not expose the parent credentials in browser instructions.
+
+Credentials must remain valid through queuing, processing, upload retries, and verification. The Robot does not refresh them. Signed download URLs cannot outlive the credentials that sign them, even when \`sign_urls_for\` is longer.
+
+When overriding a stored \`key\` or \`secret\` with a different value, supply the matching \`session_token\` inline too; the stored token will not be inherited. When updating Cloudflare Template Credentials, replacing either key or secret without a new token removes the old token. Omitting the token retains it only when the key and secret stay unchanged. You can also explicitly remove it with an empty string or \`null\`; empty tokens are treated as absent on creation too.
+
+For locally signed credentials using explicit R2 \`actions\`, grant \`PutObject\` for small uploads and \`HeadObject\` for the Robot’s mandatory signed HEAD verification. Uploads larger than the default 5 MiB part size use multipart requests: also grant \`CreateMultipartUpload\`, \`UploadPart\`, \`CompleteMultipartUpload\`, and \`AbortMultipartUpload\` for failed-upload cleanup. Grant \`GetObject\` if consumers will use signed download URLs. These are R2 action names, not AWS IAM policy actions.
+
+Scope \`paths.objectPaths\` to the exact destination object key and set \`path\` to that same key. A path ending in \`/\` appends a generated filename and will not match an exact-object grant. Use one output per exact-object key to avoid overwrites. No bucket listing or region-discovery permission is needed.
+
+Strictly write-only credentials cannot pass this Robot’s HEAD verification. For uploads without read verification, use [/s3/store](/docs/robots/s3-store/) with the R2 configuration documented there. A presigned PUT URL is a different credential format and cannot be used as this Robot’s \`host\`.
 `,
   has_small_icon: true,
   purpose_sentence: 'exports encoding results to Cloudflare R2 buckets',
@@ -39,6 +53,12 @@ export const robotCloudflareStoreInstructionsSchema = robotBase
   .extend({
     robot: z.literal('/cloudflare/store'),
     path: storeFilePath,
+    session_token: z
+      .string()
+      .optional()
+      .describe(`
+The session token belonging to the temporary Cloudflare R2 access key ID and secret access key supplied for this upload. It can also be supplied inside Template Credentials. The credentials must remain valid through upload and signed HEAD verification; the Robot does not refresh them.
+`),
     headers: z
       .record(z.string())
       .default({ 'Content-Type': '${file.mime}' })

package/src/alphalib/types/robots/document-convert.ts

@@ -11,6 +11,7 @@ import {
   documentConvertLoadInternalErrorReason,
   documentConvertLoadUserErrorReason,
 } from '../responseErrors/DocumentConvertRobot.ts'
+import { htmlPdfReadinessDescription } from './_html-pdf.ts'
 import {
   createProcessingExample,
   defineRobot,
@@ -119,6 +120,8 @@ export const robotDocumentConvertInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
     robot: z.literal('/document/convert').describe(`
+${htmlPdfReadinessDescription}
+
 > [!Note]
 > This Robot can convert files to PDF, but cannot convert PDFs to different formats. If you want to convert PDFs to say, JPEG or TIFF, use [🤖/image/resize](/docs/robots/image-resize/). If you want to turn them into text files or recognize (OCR) them to make them searchable, reach out, as we have a new Robot in the works for this.
 

package/src/alphalib/types/robots/html-convert.ts

@@ -6,6 +6,7 @@ import type {
 
 import { z } from 'zod'
 
+import { htmlPdfReadinessDescription } from './_html-pdf.ts'
 import {
   defineRobotWithHiddenFields,
   robotBase,
@@ -50,6 +51,8 @@ export const robotHtmlConvertInstructionsSchema = robotBase
 A URL can be provided instead of an input HTML file, to capture a screenshot from the website referenced by the URL.
 
 Use [🤖/image/resize](/docs/robots/image-resize/) to resize or crop the screenshot as needed.
+
+${htmlPdfReadinessDescription}
 `),
     url: z
       .string()

package/src/alphalib/types/robots/s3-store.ts

@@ -36,6 +36,32 @@ export const meta: RobotMetaInput = {
   ...robotStoreMeta,
   example_code: createStorageStoreExample('/s3/store', 'YOUR_AWS_CREDENTIALS'),
   example_code_description: 'Export uploaded files to `my_target_folder` in an S3 bucket:',
+  extended_description: `
+## Export to R2 with temporary credentials
+
+To upload one output to an exact R2 object key, send the matching temporary credentials from your trusted backend:
+
+\`\`\`json
+{
+  "robot": "/s3/store",
+  "use": ":original",
+  "host": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
+  "bucket": "my-bucket",
+  "bucket_region": "auto",
+  "acl": "bucket-default",
+  "key": "TEMPORARY_ACCESS_KEY_ID",
+  "secret": "TEMPORARY_SECRET_ACCESS_KEY",
+  "session_token": "TEMPORARY_SESSION_TOKEN",
+  "path": "exports/result.jpg"
+}
+\`\`\`
+
+The HTTPS host enables TLS, \`bucket_region: "auto"\` avoids region discovery, and \`acl: "bucket-default"\` omits the generated ACL header. Do not add ACL or grant headers. Scope the [R2 temporary credentials](https://developers.cloudflare.com/r2/api/s3/temporary-credentials/) to the same bucket and exact object key, here \`exports/result.jpg\`. Do not end \`path\` with \`/\`: that appends a generated filename. Export one output per key to avoid overwrites.
+
+For locally signed R2 credentials, \`actions: ["PutObject"]\` permits small single-request uploads with this configuration. Uploads larger than the default 5 MiB part size also require \`CreateMultipartUpload\`, \`UploadPart\`, \`CompleteMultipartUpload\`, and \`AbortMultipartUpload\` for failed-upload cleanup. These are R2 action names, not AWS IAM policy actions. No listing, region discovery, HEAD, or GET is required by this upload configuration. Unlike [/cloudflare/store](/docs/robots/cloudflare-store/), this Robot does not perform HEAD verification after upload.
+
+Credentials must remain valid through queuing, processing, and upload retries; the Robot does not refresh them. A returned object URL does not grant read access. If you request signed download URLs with \`sign_urls_for\`, add \`GetObject\` permission; those URLs also expire when the temporary credentials expire. A presigned PUT URL cannot be used as \`host\`.
+`,
   has_small_icon: true,
   purpose_sentence: 'exports encoding results to Amazon S3',
   purpose_word: 'Amazon S3',
@@ -155,7 +181,7 @@ This parameter provides signed URLs in the result JSON (in the \`signed_url\` an
       .string()
       .optional()
       .describe(`
-The session token belonging to the temporary AWS access key ID and secret access key supplied for this upload. The Robot does not assume a role or refresh these credentials; they must remain valid for the upload.
+The session token belonging to the temporary access key ID and secret access key supplied for this upload to S3 or a compatible service such as R2. The Robot does not assume a role or refresh these credentials; they must remain valid for the upload.
 `),
   })
   .strict()

package/src/alphalib/types/robots/text-speak.ts

@@ -28,30 +28,6 @@ export const meta: RobotMetaInput = {
   extended_description: `
 > [!Warning]
 > Transloadit aims to be deterministic, but this <dfn>Robot</dfn> uses third-party AI services. The providers (AWS, GCP) will evolve their models over time, giving different responses for the same input media. Avoid relying on exact responses in your tests and application.
-
-## Supported languages and voices
-
-{% for provider in text_speak_voices %}
-
-### {{provider[0] | upcase }}
-
-<table class="table">
-  <thead>
-    <tr>
-      <th>Language</th>
-      <th>Voices</th>
-    </tr>
-  </thead>
-  <tbody>
-    {%- for language in provider[1] %}
-      <tr>
-        <td><strong>{{language[0]}}</strong></td>
-        <td>{{ language[1] | join: ", " }}</td>
-      </tr>
-    {%- endfor %}
-  </tbody>
-</table>
-{% endfor %}
 `,
   override_lvl1: 'Artificial Intelligence',
   purpose_sentence: 'synthesizes speech in documents',

package/src/alphalib/types/robots/text-translate.ts

@@ -26,19 +26,6 @@ export const meta: RobotMetaInput = {
   extended_description: `
 > [!Warning]
 > This <dfn>Robot</dfn> uses third-party AI services. They may tweak their models over time, giving different responses for the same input media. Avoid relying on exact responses in your tests and application.
-
-## Supported languages
-
-{%- for provider in text_translate_languages %}
-
-### {{provider[0] | upcase }}
-
-<!-- prettier-ignore -->
-{%- for language in provider[1] %}
-  {{ language }}{% unless forloop.last %},{% endunless %}
-{%- endfor %}
-
-{%- endfor %}
 `,
   override_lvl1: 'Artificial Intelligence',
   purpose_sentence: 'translates text in documents',

package/src/alphalib/types/robots/video-encode.ts

@@ -45,6 +45,8 @@ Videos recorded with iPhone spatial audio can contain a stereo AAC track alongsi
 
 Files containing only unsupported audio still fail. Individual audio track selections and stream-copy requests keep the tracks you select; the output format must support copied tracks.
 
+When adding watermarks or drawing with simple FFmpeg video filters such as \`drawtext\` to HLG or PQ HDR video, the video is tone-mapped to SDR BT.709 before drawing, so overlay colors retain their intended RGB values. SDR inputs keep their existing processing. A custom \`ffmpeg.pre:filter:v\` that supplies tone mapping controls its own color conversion. Custom multi-input \`filter_complex\` graphs must handle each input’s color space explicitly.
+
 ## Adding text overlays with FFmpeg
 
 You can add text overlays to videos using FFmpeg's \`drawtext\` filter through this <dfn>Robot</dfn>'s \`ffmpeg\` parameter. Here are two examples — one with the default font and one with a custom font family name:

package/src/alphalib/types/robots/video-generate.ts

@@ -11,6 +11,7 @@ import {
   robotParameterDocs,
   robotUse,
 } from './_instructions-primitives.ts'
+import { videoGenerationParameterEnforcementDate } from './_video-generate-description.ts'
 
 export const meta: RobotMetaInput = {
   ...robotArtificialIntelligenceMeta,
@@ -19,8 +20,6 @@ export const meta: RobotMetaInput = {
       generated_video: {
         robot: '/video/generate',
         prompt: 'A slow cinematic drone shot of ocean cliffs at sunrise, realistic lighting.',
-        duration: 5,
-        aspect_ratio: '16:9',
         format: 'mp4',
       },
     },
@@ -46,15 +45,18 @@ export const robotVideoGenerateInstructionsSchema = robotBase
       .string()
       .optional()
       .describe(
-        `The AI model to use for video generation. Defaults to ${videoGenerateDefaultModelIdentifier}.`,
+        `Video model; defaults to ${videoGenerateDefaultModelIdentifier}. Unsupported settings warn until ${videoGenerationParameterEnforcementDate}. MiniMax outputs are about six seconds.`,
       ),
     prompt: z.string().describe('The prompt describing the desired video content.'),
     format: z.enum(['mp4']).optional().describe('Format of the generated video.'),
     seed: z.number().optional().describe(robotParameterDocs.seed.description),
-    aspect_ratio: z.string().optional().describe('Aspect ratio of the generated video.'),
-    height: z.number().optional().describe('Height of the generated video.'),
-    width: z.number().optional().describe('Width of the generated video.'),
-    style: z.string().optional().describe('Style of the generated video.'),
+    aspect_ratio: z
+      .string()
+      .optional()
+      .describe('Aspect ratio for lightricks/ltx-video without an input image.'),
+    height: z.number().optional().describe('Pixel height for tencent/hunyuan-video.'),
+    width: z.number().optional().describe('Pixel width for tencent/hunyuan-video.'),
+    style: z.string().optional().describe('Unsupported by current models; omit it.'),
     num_outputs: z
       .number()
       .int()
@@ -62,26 +64,12 @@ export const robotVideoGenerateInstructionsSchema = robotBase
       .max(10)
       .optional()
       .describe('Number of video variants to generate.'),
-    duration: z.number().optional().describe('Duration of the generated video in seconds.'),
-    fps: z.number().optional().describe('Frames per second of the output video.'),
-    motion_amount: z
-      .number()
-      .optional()
-      .describe('Controls the intensity of motion in the generated video.'),
-    camera_motion: z
-      .string()
-      .optional()
-      .describe(
-        'Camera movement type (e.g., pan-left, pan-right, zoom-in, zoom-out, orbit, static, dolly, crane).',
-      ),
-    negative_prompt: z
-      .string()
-      .optional()
-      .describe('Describes what should be avoided in the generated video.'),
-    reference_strength: z
-      .number()
-      .optional()
-      .describe('How closely the output should follow the reference input (0.0 - 1.0).'),
+    duration: z.number().optional().describe('Unsupported by current models; omit it.'),
+    fps: z.number().optional().describe('Frames per second for tencent/hunyuan-video.'),
+    motion_amount: z.number().optional().describe('Unsupported by current models; omit it.'),
+    camera_motion: z.string().optional().describe('Unsupported by current models; omit it.'),
+    negative_prompt: z.string().optional().describe('Content to avoid (lightricks/ltx-video).'),
+    reference_strength: z.number().optional().describe('Unsupported by current models; omit it.'),
   })
   .strict()
 

package/src/alphalib/types/robots/video-subtitle.ts

@@ -77,6 +77,8 @@ export const robotVideoSubtitleInstructionsSchema = robotBase
 This <dfn>Robot</dfn> supports SRT, VTT, ASS, and the timestamped JSON output of \`/speech/transcribe\` with \`"format": "json"\`. Pass the video as \`"video"\` and the transcript as \`"subtitles"\` in the \`use\` parameter. JSON words are grouped into captions and converted to ASS for burned word highlighting, or plain SRT cues for external subtitle streams. External JSON cues preserve casing and punctuation. Provider segments do not control caption breaks. SRT and VTT timing is preserved.
 
 Without a \`preset\` or custom \`ffmpeg\` options, the legacy \`"flash"\` preset produces FLV output. With this default, burned subtitles use MP3 audio; external subtitles copy the input audio. Set \`"preset": "empty"\` to keep the input container, such as MP4 for an MP4 input.
+
+When burning subtitles into HLG or PQ HDR video, the video is tone-mapped to SDR BT.709 before captions are drawn. Caption colors retain their intended RGB values, and the output is tagged as SDR. External subtitles preserve the source video’s HDR colors. SDR inputs keep their existing processing. If \`ffmpeg.pre:filter:v\` supplies its own tone mapping, that filter controls color conversion.
 `),
     subtitles_type: zodInputPreservingTransform(z.enum(['burned', 'external', 'burn']), (val) =>
       val === 'burn' ? 'burned' : val,

package/src/alphalib/types/robots/video-thumbs.ts

@@ -70,6 +70,8 @@ export const robotVideoThumbsInstructionsSchema = robotBase
     robot: z.literal('/video/thumbs').describe(`
 Set \`smart: true\` to select strong preview images with AI instead of taking frames only at regular intervals. The Robot scores candidate frames for clarity, brightness, composition, faces, expressions, action, and visual interest, then returns the best \`count\` frames in chronological order. Smart results include \`file.meta.smart_score\` and \`file.meta.smart_reasons\`. If AI scoring is unavailable, the Assembly continues with the candidate frames in fallback order and includes a warning. No AI credentials are required.
 
+HLG and PQ HDR video frames are tone-mapped to SDR sRGB before image encoding, including smart-thumbnail candidates. This preserves the intended appearance in browsers that display thumbnails as sRGB images. SDR inputs keep their existing processing.
+
 ## AI pricing
 
 Regular \`/video/thumbs\` processing charges still apply. AI frame analysis is billed separately at the underlying provider cost plus a ${smartThumbnailMarkupPercent}% Transloadit markup. Smart selection uses the dedicated \`${smartThumbnailModel}\` vision model with \`${smartThumbnailReasoningEffort}\` reasoning, independently of the \`/ai/chat\` default. The exact AI charge varies with the number of candidate frames and provider pricing.

package/src/cli/commands/assemblies.ts

@@ -484,12 +484,16 @@ function getJobInputPath(filepath: string): string {
   return normalizedFile
 }
 
-function createInputUploadStream(filepath: string): Readable {
-  const instream = fs.createReadStream(filepath)
-  // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-  // before being consumed (e.g., due to output collision detection)
-  instream.on('error', () => {})
-  return instream
+function hasPipedStdin(): boolean {
+  if (process.stdin.isTTY) return false
+
+  try {
+    const stats = fs.fstatSync(process.stdin.fd)
+    return stats.isFIFO() || stats.isFile()
+  } catch {
+    // A closed or unavailable descriptor is not an implicit upload.
+    return false
+  }
 }
 
 function createOutputPlan(pathname: string | undefined, mtime: Date): OutputPlan {
@@ -747,7 +751,7 @@ async function resolveResultDownloadTargets({
     return await buildDirectoryDownloadTargets({
       allFiles,
       baseDir: outputRoot,
-      groupByStep: false,
+      groupByStep: inputs.length === 0,
       reservedPaths,
     })
   }
@@ -756,7 +760,7 @@ async function resolveResultDownloadTargets({
     return await buildDirectoryDownloadTargets({
       allFiles,
       baseDir: resolveDirectoryBaseDir(),
-      groupByStep: entries.length > 1,
+      groupByStep: inPath == null || entries.length > 1,
       reservedPaths,
     })
   }
@@ -1592,7 +1596,7 @@ export async function create(
       const uploads =
         inPath === stdinWithPath.path
           ? {
-              in: createInputUploadStream(inPath),
+              in: process.stdin,
             }
           : undefined
 
@@ -1660,7 +1664,7 @@ export async function create(
             scope: collection,
           })
           if (inPath === stdinWithPath.path) {
-            uploads[key] = createInputUploadStream(inPath)
+            uploads[key] = process.stdin
           } else {
             files[key] = inPath
           }
@@ -1802,6 +1806,8 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
     details: `
       Create assemblies to process media files using Transloadit.
       You must specify either --steps or --template.
+      Without uploads, directory outputs are saved as <output>/<step>/<result name>.
+      Stdin is read with --input -, or implicitly with --steps when piped or redirected from a file.
     `,
     examples: [
       [
@@ -1812,6 +1818,10 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
         'Process with a template',
         'transloadit assemblies create --template TEMPLATE_ID -i input.jpg -o output/',
       ],
+      [
+        'Download results from import-only or prompt-only steps',
+        'transloadit assemblies create --steps steps.json -o output/',
+      ],
       [
         'Watch for changes',
         'transloadit assemblies create --steps steps.json -i input/ -o output/ --watch',
@@ -1864,9 +1874,8 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
 
     const inputList = this.inputs ?? []
 
-    // Default to stdin only for `--steps` mode (common "pipe a file into a one-off assembly" use case).
-    // For `--template` mode, templates may be inputless or use /http/import, so stdin should be explicit (`--input -`).
-    if (this.steps && inputList.length === 0 && !process.stdin.isTTY) {
+    // Templates keep requiring explicit stdin; steps also accept pipes and redirected files.
+    if (this.steps && inputList.length === 0 && hasPipedStdin()) {
       inputList.push('-')
     }
 
@@ -1975,7 +1984,7 @@ export class RunCommand extends AuthenticatedCommand {
   protected async run(): Promise<number | undefined> {
     const inputList = this.inputs ?? []
 
-    if (inputList.length === 0 && !process.stdin.isTTY) {
+    if (inputList.length === 0 && hasPipedStdin()) {
       inputList.push('-')
     }