@transloadit/zod 4.3.0 → 4.3.2

package/dist/v3/robots/image-enhance.js

@@ -0,0 +1,145 @@
+import { z } from 'zod/v3';
+import { imageQualitySchema, interpolateRobot, robotBase, robotImagemagick, robotUse, } from "./_instructions-primitives.js";
+export const meta = {
+    bytescount: 1,
+    discount_factor: 1,
+    discount_pct: 0,
+    example_code: {
+        steps: {
+            enhanced_classic: {
+                robot: '/image/enhance',
+                use: ':original',
+                enhance: 'auto',
+                preset: 'vivid',
+            },
+            enhanced_ai: {
+                robot: '/image/enhance',
+                use: ':original',
+                engine: 'ai',
+                ai_preset: 'restore',
+            },
+        },
+    },
+    example_code_description: 'Enhance uploaded images with classic auto mode or AI restoration:',
+    minimum_charge: 0,
+    output_factor: 0.6,
+    override_lvl1: 'Image Manipulation',
+    purpose_sentence: 'automatically enhances images by adjusting levels, contrast, and sharpness, and optionally applies photo filter presets',
+    purpose_verb: 'enhance',
+    purpose_word: 'enhance',
+    purpose_words: 'Enhance images',
+    service_slug: 'image-manipulation',
+    slot_count: 15,
+    title: 'Enhance images',
+    typical_file_size_mb: 1.2,
+    typical_file_type: 'image',
+    name: 'ImageEnhanceRobot',
+    priceFactor: 1,
+    queueSlotCount: 15,
+    isAllowedForUrlTransform: true,
+    trackOutputFileSize: true,
+    isInternal: false,
+    removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+    stage: 'beta',
+};
+const enhanceModeSchema = z.enum(['auto', 'auto_gentle', 'auto_aggressive', 'none']).default('auto');
+const presetSchema = z
+    .enum([
+    'none',
+    'warm',
+    'cool',
+    'vintage',
+    'vivid',
+    'matte',
+    'cinematic',
+    'golden_hour',
+    'bw_dramatic',
+    'bw_classic',
+    'noir',
+    'fade',
+    'pastel',
+    'teal_orange',
+])
+    .default('none');
+const engineSchema = z.enum(['classic', 'ai']).default('classic');
+const aiPresetSchema = z.enum(['restore', 'face_restore']).default('restore');
+export const robotImageEnhanceInstructionsSchema = robotBase
+    .merge(robotUse)
+    .merge(robotImagemagick)
+    .extend({
+    robot: z.literal('/image/enhance').describe(`
+With this <dfn>Robot</dfn> you can automatically enhance images with one click — adjusting levels, contrast, saturation, sharpness, and white balance to produce an optimally balanced image. It also supports a library of named photo filter presets (e.g. \`warm\`, \`cool\`, \`vintage\`, \`vivid\`) that apply curated color grading and tone adjustments.
+
+It works well together with [🤖/image/resize](/docs/robots/image-resize/) — you can enhance first, then resize, or vice versa.
+
+> [!Note]
+> This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and will pass through unsupported types unchanged.
+
+> [!Note]
+> \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`. \`engine: "ai"\` uses \`ai_preset\` and \`quality\`; classic controls are ignored in AI mode.
+
+> [!Note]
+> Output keeps the original file extension when possible. In AI mode, if the target extension is not writable by the selected \`imagemagick_stack\`, the file is passed through unchanged.
+`),
+    enhance: enhanceModeSchema.describe(`
+The auto-enhancement mode. \`"auto"\` applies balanced auto-levels, gamma correction, and subtle sharpening. \`"auto_gentle"\` is more conservative (good for already-decent photos). \`"auto_aggressive"\` applies stronger normalization and contrast. \`"none"\` skips auto-enhance (useful when only applying a preset filter).
+`),
+    preset: presetSchema.describe(`
+A named color grading preset to apply. Applied after auto-enhancement. Use \`"none"\` to skip preset application.
+
+Available presets:
+- \`warm\` — Warm golden tones
+- \`cool\` — Cool blue-shifted tones
+- \`vintage\` — Faded retro look with warm shadows
+- \`vivid\` — Boosted saturation and contrast
+- \`matte\` — Lifted blacks for a matte film look
+- \`cinematic\` — Teal-and-orange cinema grading
+- \`golden_hour\` — Warm sunset-like glow
+- \`bw_dramatic\` — High-contrast black and white
+- \`bw_classic\` — Classic film black and white
+- \`noir\` — Dark, moody black and white
+- \`fade\` — Washed-out faded look
+- \`pastel\` — Soft, desaturated pastel tones
+- \`teal_orange\` — Complementary teal shadows and orange highlights
+`),
+    engine: engineSchema.describe(`
+Enhancement engine to use.
+
+- \`"classic"\` uses ImageMagick-based adjustments and presets.
+- \`"ai"\` uses AI restoration models on Replicate (typically higher latency and cost than classic mode).
+`),
+    ai_preset: aiPresetSchema.describe(`
+AI enhancement preset used when \`engine\` is set to \`"ai"\`:
+- \`restore\` — General image restoration.
+- \`face_restore\` — Portrait-focused face restoration.
+
+AI mode is not intended for image upscaling. For dedicated upscaling, use [🤖/image/upscale](/docs/robots/image-upscale/).
+`),
+    sharpen: z
+        .number()
+        .min(0)
+        .max(10)
+        .default(0)
+        .describe(`
+Additional sharpening amount (\`0\` = none, \`10\` = maximum). The \`"auto"\` enhance mode already applies subtle sharpening; this parameter adds more on top.
+`),
+    denoise: z
+        .number()
+        .min(0)
+        .max(10)
+        .default(0)
+        .describe(`
+Noise reduction strength (\`0\` = none, \`10\` = maximum). Useful for high-ISO photos.
+`),
+    quality: imageQualitySchema.describe(`
+Quality of the output image. A value between \`1\` and \`100\`. Defaults to \`92\`.
+`),
+})
+    .strict();
+export const robotImageEnhanceInstructionsWithHiddenFieldsSchema = robotImageEnhanceInstructionsSchema.extend({
+    result: z
+        .union([z.literal('debug'), robotImageEnhanceInstructionsSchema.shape.result])
+        .optional(),
+});
+export const interpolatableRobotImageEnhanceInstructionsSchema = interpolateRobot(robotImageEnhanceInstructionsSchema);
+export const interpolatableRobotImageEnhanceInstructionsWithHiddenFieldsSchema = interpolateRobot(robotImageEnhanceInstructionsWithHiddenFieldsSchema);

package/dist/v3/robots/image-facedetect.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod/v3';
 import type { RobotMetaInput } from './_instructions-primitives.ts';
 export declare const meta: RobotMetaInput;
 export declare const robotImageFacedetectInstructionsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
     result: z.ZodDefault<z.ZodBoolean>;
     queue: z.ZodOptional<z.ZodEnum<["batch"]>>;
@@ -74,6 +75,7 @@ export declare const robotImageFacedetectInstructionsSchema: z.ZodObject<{
     crop_padding: string;
     min_confidence: number;
     faces: number | "each" | "group" | "max-confidence" | "max-size";
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -93,6 +95,7 @@ export declare const robotImageFacedetectInstructionsSchema: z.ZodObject<{
     provider?: "aws" | "gcp" | "replicate" | "fal" | "transloadit" | undefined;
 }, {
     robot: "/image/facedetect";
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -120,6 +123,7 @@ export declare const robotImageFacedetectInstructionsSchema: z.ZodObject<{
     faces?: number | "each" | "group" | "max-confidence" | "max-size" | undefined;
 }>;
 export declare const robotImageFacedetectInstructionsWithHiddenFieldsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
     queue: z.ZodOptional<z.ZodEnum<["batch"]>>;
     force_accept: z.ZodDefault<z.ZodBoolean>;
@@ -190,6 +194,7 @@ export declare const robotImageFacedetectInstructionsWithHiddenFieldsSchema: z.Z
     crop_padding: string;
     min_confidence: number;
     faces: number | "each" | "group" | "max-confidence" | "max-size";
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -210,6 +215,7 @@ export declare const robotImageFacedetectInstructionsWithHiddenFieldsSchema: z.Z
     provider?: "aws" | "gcp" | "replicate" | "fal" | "transloadit" | undefined;
 }, {
     robot: "/image/facedetect";
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -239,6 +245,7 @@ export declare const robotImageFacedetectInstructionsWithHiddenFieldsSchema: z.Z
 export type RobotImageFacedetectInstructions = z.infer<typeof robotImageFacedetectInstructionsSchema>;
 export type RobotImageFacedetectInstructionsWithHiddenFields = z.infer<typeof robotImageFacedetectInstructionsWithHiddenFieldsSchema>;
 export declare const interpolatableRobotImageFacedetectInstructionsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>]>>;
     result: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["batch"]>]>>;
@@ -309,6 +316,7 @@ export declare const interpolatableRobotImageFacedetectInstructionsSchema: z.Zod
     crop_padding: string;
     min_confidence: string | number;
     faces: string | number;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -328,6 +336,7 @@ export declare const interpolatableRobotImageFacedetectInstructionsSchema: z.Zod
     provider?: string | undefined;
 }, {
     robot: "/image/facedetect";
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -357,6 +366,7 @@ export declare const interpolatableRobotImageFacedetectInstructionsSchema: z.Zod
 export type InterpolatableRobotImageFacedetectInstructions = InterpolatableRobotImageFacedetectInstructionsInput;
 export type InterpolatableRobotImageFacedetectInstructionsInput = z.input<typeof interpolatableRobotImageFacedetectInstructionsSchema>;
 export declare const interpolatableRobotImageFacedetectInstructionsWithHiddenFieldsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>]>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["batch"]>]>>;
     force_accept: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
@@ -426,6 +436,7 @@ export declare const interpolatableRobotImageFacedetectInstructionsWithHiddenFie
     crop_padding: string;
     min_confidence: string | number;
     faces: string | number;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -446,6 +457,7 @@ export declare const interpolatableRobotImageFacedetectInstructionsWithHiddenFie
     provider?: string | undefined;
 }, {
     robot: "/image/facedetect";
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;

package/dist/v3/robots/image-facedetect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-facedetect.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/image-facedetect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAQnE,eAAO,MAAM,IAAI,EAAE,cAwClB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGxC,CAAA;AAEX,eAAO,MAAM,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK/D,CAAA;AAEJ,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CACpD,OAAO,sCAAsC,CAC9C,CAAA;AACD,MAAM,MAAM,gDAAgD,GAAG,CAAC,CAAC,KAAK,CACpE,OAAO,sDAAsD,CAC9D,CAAA;AAED,eAAO,MAAM,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEhE,CAAA;AACD,MAAM,MAAM,8CAA8C,GACxD,mDAAmD,CAAA;AAErD,MAAM,MAAM,mDAAmD,GAAG,CAAC,CAAC,KAAK,CACvE,OAAO,oDAAoD,CAC5D,CAAA;AAED,eAAO,MAAM,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACP,CAAA;AAC1E,MAAM,MAAM,8DAA8D,GAAG,CAAC,CAAC,KAAK,CAClF,OAAO,oEAAoE,CAC5E,CAAA;AACD,MAAM,MAAM,mEAAmE,GAAG,CAAC,CAAC,KAAK,CACvF,OAAO,oEAAoE,CAC5E,CAAA"}
+{"version":3,"file":"image-facedetect.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/image-facedetect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAQnE,eAAO,MAAM,IAAI,EAAE,cAuClB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGxC,CAAA;AAEX,eAAO,MAAM,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK/D,CAAA;AAEJ,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CACpD,OAAO,sCAAsC,CAC9C,CAAA;AACD,MAAM,MAAM,gDAAgD,GAAG,CAAC,CAAC,KAAK,CACpE,OAAO,sDAAsD,CAC9D,CAAA;AAED,eAAO,MAAM,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEhE,CAAA;AACD,MAAM,MAAM,8CAA8C,GACxD,mDAAmD,CAAA;AAErD,MAAM,MAAM,mDAAmD,GAAG,CAAC,CAAC,KAAK,CACvE,OAAO,oDAAoD,CAC5D,CAAA;AAED,eAAO,MAAM,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACP,CAAA;AAC1E,MAAM,MAAM,8DAA8D,GAAG,CAAC,CAAC,KAAK,CAClF,OAAO,oEAAoE,CAC5E,CAAA;AACD,MAAM,MAAM,mEAAmE,GAAG,CAAC,CAAC,KAAK,CACvF,OAAO,oEAAoE,CAC5E,CAAA"}

package/dist/v3/robots/image-facedetect.js

@@ -1,7 +1,6 @@
 import { z } from 'zod/v3';
 import { aiProviderSchema, interpolateRobot, robotBase, robotUse, } from "./_instructions-primitives.js";
 export const meta = {
-    allowed_for_url_transform: true,
     bytescount: 1,
     discount_factor: 1,
     discount_pct: 0,

package/dist/v3/robots/image-generate.d.ts

@@ -2,12 +2,14 @@ import { z } from 'zod/v3';
 import type { RobotMetaInput } from './_instructions-primitives.ts';
 export declare const meta: RobotMetaInput;
 export declare const robotImageGenerateInstructionsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
     result: z.ZodDefault<z.ZodBoolean>;
     queue: z.ZodOptional<z.ZodEnum<["batch"]>>;
     force_accept: z.ZodDefault<z.ZodBoolean>;
     ignore_errors: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodArray<z.ZodEnum<["meta", "execute"]>, "many">]>, string[], boolean | ("meta" | "execute")[]>>;
 } & {
+    robot: z.ZodLiteral<"/image/generate">;
     use: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         fields: z.ZodOptional<z.ZodString>;
@@ -56,8 +58,6 @@ export declare const robotImageGenerateInstructionsSchema: z.ZodObject<{
         bundle_steps?: boolean | undefined;
         group_by_original?: boolean | undefined;
     }>]>>;
-} & {
-    robot: z.ZodLiteral<"/image/generate">;
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     format: z.ZodOptional<z.ZodEnum<["jpeg", "jpg", "png", "gif", "webp", "svg"]>>;
@@ -73,6 +73,7 @@ export declare const robotImageGenerateInstructionsSchema: z.ZodObject<{
     force_accept: boolean;
     ignore_errors: string[];
     prompt: string;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -100,6 +101,7 @@ export declare const robotImageGenerateInstructionsSchema: z.ZodObject<{
 }, {
     robot: "/image/generate";
     prompt: string;
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -129,10 +131,12 @@ export declare const robotImageGenerateInstructionsSchema: z.ZodObject<{
     num_outputs?: number | undefined;
 }>;
 export declare const robotImageGenerateInstructionsWithHiddenFieldsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodBoolean>, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
     queue: z.ZodOptional<z.ZodEnum<["batch"]>>;
     force_accept: z.ZodDefault<z.ZodBoolean>;
     ignore_errors: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodArray<z.ZodEnum<["meta", "execute"]>, "many">]>, string[], boolean | ("meta" | "execute")[]>>;
+    robot: z.ZodLiteral<"/image/generate">;
     use: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         fields: z.ZodOptional<z.ZodString>;
@@ -181,7 +185,6 @@ export declare const robotImageGenerateInstructionsWithHiddenFieldsSchema: z.Zod
         bundle_steps?: boolean | undefined;
         group_by_original?: boolean | undefined;
     }>]>>;
-    robot: z.ZodLiteral<"/image/generate">;
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     format: z.ZodOptional<z.ZodEnum<["jpeg", "jpg", "png", "gif", "webp", "svg"]>>;
@@ -199,6 +202,7 @@ export declare const robotImageGenerateInstructionsWithHiddenFieldsSchema: z.Zod
     force_accept: boolean;
     ignore_errors: string[];
     prompt: string;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -228,6 +232,7 @@ export declare const robotImageGenerateInstructionsWithHiddenFieldsSchema: z.Zod
 }, {
     robot: "/image/generate";
     prompt: string;
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -260,10 +265,12 @@ export declare const robotImageGenerateInstructionsWithHiddenFieldsSchema: z.Zod
 export type RobotImageGenerateInstructions = z.infer<typeof robotImageGenerateInstructionsSchema>;
 export type RobotImageGenerateInstructionsWithHiddenFields = z.infer<typeof robotImageGenerateInstructionsWithHiddenFieldsSchema>;
 export declare const interpolatableRobotImageGenerateInstructionsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>]>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["batch"]>]>>;
     force_accept: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     ignore_errors: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodArray<z.ZodEnum<["meta", "execute"]>, "many">]>, string[], boolean | ("meta" | "execute")[]>]>>;
+    robot: z.ZodLiteral<"/image/generate">;
     use: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         fields: z.ZodOptional<z.ZodString>;
@@ -312,7 +319,6 @@ export declare const interpolatableRobotImageGenerateInstructionsSchema: z.ZodOb
         bundle_steps?: boolean | undefined;
         group_by_original?: boolean | undefined;
     }>]>>;
-    robot: z.ZodLiteral<"/image/generate">;
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     format: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["jpeg", "jpg", "png", "gif", "webp", "svg"]>]>>;
@@ -329,6 +335,7 @@ export declare const interpolatableRobotImageGenerateInstructionsSchema: z.ZodOb
     force_accept: string | boolean;
     ignore_errors: string | string[];
     prompt: string;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -358,6 +365,7 @@ export declare const interpolatableRobotImageGenerateInstructionsSchema: z.ZodOb
 }, {
     robot: "/image/generate";
     prompt: string;
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -390,10 +398,12 @@ export declare const interpolatableRobotImageGenerateInstructionsSchema: z.ZodOb
 export type InterpolatableRobotImageGenerateInstructions = InterpolatableRobotImageGenerateInstructionsInput;
 export type InterpolatableRobotImageGenerateInstructionsInput = z.input<typeof interpolatableRobotImageGenerateInstructionsSchema>;
 export declare const interpolatableRobotImageGenerateInstructionsWithHiddenFieldsSchema: z.ZodObject<{
+    interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "false" | "true">>]>>;
     output_meta: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, z.ZodUnion<[z.ZodString, z.ZodBoolean]>, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>]>>;
     queue: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["batch"]>]>>;
     force_accept: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     ignore_errors: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodArray<z.ZodEnum<["meta", "execute"]>, "many">]>, string[], boolean | ("meta" | "execute")[]>]>>;
+    robot: z.ZodLiteral<"/image/generate">;
     use: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         fields: z.ZodOptional<z.ZodString>;
@@ -442,7 +452,6 @@ export declare const interpolatableRobotImageGenerateInstructionsWithHiddenField
         bundle_steps?: boolean | undefined;
         group_by_original?: boolean | undefined;
     }>]>>;
-    robot: z.ZodLiteral<"/image/generate">;
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     format: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEnum<["jpeg", "jpg", "png", "gif", "webp", "svg"]>]>>;
@@ -459,6 +468,7 @@ export declare const interpolatableRobotImageGenerateInstructionsWithHiddenField
     force_accept: string | boolean;
     ignore_errors: string | string[];
     prompt: string;
+    interpolate?: boolean | Record<string, boolean> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;
@@ -488,6 +498,7 @@ export declare const interpolatableRobotImageGenerateInstructionsWithHiddenField
 }, {
     robot: "/image/generate";
     prompt: string;
+    interpolate?: boolean | "false" | "true" | Record<string, boolean | "false" | "true"> | undefined;
     use?: string | string[] | {
         name: string;
         fields?: string | undefined;

package/dist/v3/robots/image-generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-generate.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/image-generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAGnE,eAAO,MAAM,IAAI,EAAE,cAyBlB,CAAA;AAED,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BtC,CAAA;AAEX,eAAO,MAAM,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM7D,CAAA;AAEJ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAA;AACjG,MAAM,MAAM,8CAA8C,GAAG,CAAC,CAAC,KAAK,CAClE,OAAO,oDAAoD,CAC5D,CAAA;AAED,eAAO,MAAM,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE9D,CAAA;AACD,MAAM,MAAM,4CAA4C,GACtD,iDAAiD,CAAA;AAEnD,MAAM,MAAM,iDAAiD,GAAG,CAAC,CAAC,KAAK,CACrE,OAAO,kDAAkD,CAC1D,CAAA;AAED,eAAO,MAAM,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE9E,CAAA;AACD,MAAM,MAAM,4DAA4D,GAAG,CAAC,CAAC,KAAK,CAChF,OAAO,kEAAkE,CAC1E,CAAA;AACD,MAAM,MAAM,iEAAiE,GAAG,CAAC,CAAC,KAAK,CACrF,OAAO,kEAAkE,CAC1E,CAAA"}
+{"version":3,"file":"image-generate.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/image-generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAGnE,eAAO,MAAM,IAAI,EAAE,cA4ClB,CAAA;AASD,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsEtC,CAAA;AAEX,eAAO,MAAM,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM7D,CAAA;AAEJ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAA;AACjG,MAAM,MAAM,8CAA8C,GAAG,CAAC,CAAC,KAAK,CAClE,OAAO,oDAAoD,CAC5D,CAAA;AAED,eAAO,MAAM,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE9D,CAAA;AACD,MAAM,MAAM,4CAA4C,GACtD,iDAAiD,CAAA;AAEnD,MAAM,MAAM,iDAAiD,GAAG,CAAC,CAAC,KAAK,CACrE,OAAO,kDAAkD,CAC1D,CAAA;AAED,eAAO,MAAM,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE9E,CAAA;AACD,MAAM,MAAM,4DAA4D,GAAG,CAAC,CAAC,KAAK,CAChF,OAAO,kEAAkE,CAC1E,CAAA;AACD,MAAM,MAAM,iEAAiE,GAAG,CAAC,CAAC,KAAK,CACrF,OAAO,kEAAkE,CAC1E,CAAA"}

package/dist/v3/robots/image-generate.js

@@ -1,10 +1,27 @@
 import { z } from 'zod/v3';
 import { interpolateRobot, robotBase, robotUse } from "./_instructions-primitives.js";
 export const meta = {
-    allowed_for_url_transform: true,
     bytescount: 1,
     discount_factor: 1,
     discount_pct: 0,
+    example_code: {
+        steps: {
+            ':original': {
+                robot: '/upload/handle',
+            },
+            inpainted: {
+                robot: '/image/generate',
+                use: [
+                    { name: ':original', as: 'image' },
+                    { name: ':original', as: 'mask' },
+                ],
+                model: 'google/nano-banana-pro',
+                prompt: 'Replace the masked area with a breaching whale. Keep the rest of the image unchanged.',
+                format: 'png',
+            },
+        },
+    },
+    example_code_description: 'Inpaint an image by uploading an original image and a mask image, then use both files in /image/generate.',
     minimum_charge: 0,
     output_factor: 0.6,
     purpose_sentence: 'generates images from text prompts using AI',
@@ -26,23 +43,60 @@ export const meta = {
     removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
     stage: 'ga',
 };
+// Internal documentation (for public docs, see transloadit.com/docs)
+//
+// Inpainting: When input files are provided via `use`, file metadata (field name, mime) is
+// prepended to the prompt so the model understands each file's role. Users should name upload
+// fields semantically (e.g., "mask", "image") or use the `as` directive. Field is checked first,
+// then `as`. Models that accept explicit image/mask inputs use these roles deterministically.
+// Models that infer roles from prompt context receive this file metadata in the prompt.
 export const robotImageGenerateInstructionsSchema = robotBase
     .merge(robotUse)
     .extend({
     robot: z.literal('/image/generate'),
+    use: robotUse.shape.use.describe(`
+Specifies which Step(s) to use as input.
+
+For inpainting, provide both the source image and mask through \`use\`, typically with:
+
+\`\`\`json
+{
+  "use": [
+    { "name": ":original", "as": "image" },
+    { "name": ":original", "as": "mask" }
+  ]
+}
+\`\`\`
+
+Best practice:
+- Tag source and mask inputs explicitly using \`as\` (or semantic upload field names)
+- Keep the prompt focused on what should change in the masked/transparent region
+- Leave the model/provider choice to the robot defaults unless you have a specific need
+`),
     model: z
         .string()
         .optional()
-        .describe('The AI model to use for image generation. Defaults to google/nano-banana.'),
-    prompt: z.string().describe('The prompt describing the desired image content.'),
+        .describe('The AI model to use. Defaults to google/nano-banana. Supported models include flux-1.1-pro-ultra, flux-schnell, recraft-v3, google/nano-banana, google/nano-banana-2, google/nano-banana-pro, openai/gpt-image-2, and stability-ai/stable-diffusion-inpainting. The legacy alias gpt-image-2 is also accepted for backwards compatibility.'),
+    prompt: z
+        .string()
+        .describe('Prompt describing the desired image. For inpainting, describe what should appear in the masked/transparent region and that the rest should stay unchanged.'),
     format: z
         .enum(['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'])
         .optional()
-        .describe('Format of the generated image.'),
+        .describe('Output format. Defaults depend on model: png for Google models and openai/gpt-image-2, svg for recraft-v3, jpeg for others. Google models currently return PNG only.'),
     seed: z.number().optional().describe('Seed for the random number generator.'),
-    aspect_ratio: z.string().optional().describe('Aspect ratio of the generated image.'),
-    height: z.number().optional().describe('Height of the generated image.'),
-    width: z.number().optional().describe('Width of the generated image.'),
+    aspect_ratio: z
+        .string()
+        .optional()
+        .describe('Requested output aspect ratio. For Google models, width/height can also be used and orientation is derived automatically when aspect_ratio is omitted.'),
+    height: z
+        .number()
+        .optional()
+        .describe('Requested output height in pixels (mainly used by Google image models and openai/gpt-image-2).'),
+    width: z
+        .number()
+        .optional()
+        .describe('Requested output width in pixels (mainly used by Google image models and openai/gpt-image-2).'),
     style: z.string().optional().describe('Style of the generated image.'),
     num_outputs: z
         .number()
@@ -50,7 +104,7 @@ export const robotImageGenerateInstructionsSchema = robotBase
         .min(1)
         .max(10)
         .optional()
-        .describe('Number of image variants to generate.'),
+        .describe('Number of output variants to generate (1-10).'),
 })
     .strict();
 export const robotImageGenerateInstructionsWithHiddenFieldsSchema = robotImageGenerateInstructionsSchema.extend({