@loonylabs/tti-middleware 1.11.0 → 1.12.0

package/README.md

@@ -45,7 +45,7 @@
   - **Eden AI**: Aggregator with access to OpenAI, Stability AI, Replicate (experimental)
   - **IONOS**: German cloud provider with OpenAI-compatible API (experimental)
 - **Character Consistency**: Generate consistent characters across multiple images (perfect for children's book illustrations)
-- **Inpainting**: Fix specific areas of a generated image without regenerating the entire scene — via Vertex AI `imagen-capability` model. Supports optional subject reference images (`maskReferenceImages`) to guide *what* gets inserted into the masked area
+- **Inpainting**: Fix specific areas of a generated image without regenerating the entire scene — via Vertex AI `imagen-capability` model.
 - **GDPR/DSGVO Compliance**: Built-in EU region support with automatic fallback
 - **Region Rotation**: Opt-in region rotation on quota errors (429) for Google Cloud — rotate through regions instead of retrying the same exhausted region
 - **Retry Logic**: Exponential backoff with jitter for transient errors (429, 408, 5xx, timeouts)
@@ -331,41 +331,6 @@ const result = await service.generate({
 - Black pixels = area preserved exactly as-is
 - Mask must have identical dimensions to `baseImage`
 
-### Guided Inpainting with Subject References
-
-Use `maskReferenceImages` to provide a reference photo of the subject to insert — e.g. "place **this** character into the masked region":
-
-```typescript
-const result = await service.generate({
-  model: 'imagen-capability',
-  prompt: 'The character standing in a bright forest clearing, photorealistic',
-  baseImage:  { base64: sceneBase64,        mimeType: 'image/png' },
-  maskImage:  { base64: maskBase64,         mimeType: 'image/png' },
-  editMode: 'inpainting-insert',
-  maskReferenceImages: [
-    {
-      base64: characterRefBase64,
-      mimeType: 'image/png',
-      subjectType: 'person',   // 'person' | 'animal' | 'product' | 'default'
-    },
-  ],
-});
-```
-
-**Subject types:**
-
-| `subjectType` | Use case |
-|---------------|----------|
-| `'person'` | Human character |
-| `'animal'` | Animal or creature |
-| `'product'` | Object, item, product |
-| `'default'` | Let the model decide (safe fallback) |
-
-**Notes:**
-- `maskReferenceImages` only works with `editMode: 'inpainting-insert'`
-- Gemini models do **not** support mask-based inpainting or `maskReferenceImages`
-- `maskReferenceImages` without `baseImage` throws a validation error
-
 ### Supported `editMode` Values
 
 | Value | Description |
@@ -442,21 +407,12 @@ interface TTIRequest {
   maskImage?: TTIReferenceImage;   // Required when baseImage is set
   maskDilation?: number;           // 0.0–1.0, default 0.01
   editMode?: 'inpainting-insert' | 'inpainting-remove' | 'background-swap' | 'outpainting';
-  maskReferenceImages?: TTIMaskReferenceImage[];  // Subject refs for guided inpainting
 
   // Retry configuration
   retry?: boolean | RetryOptions;  // true (default), false, or custom config
 
   providerOptions?: Record<string, unknown>;
 }
-
-type TTISubjectType = 'person' | 'animal' | 'product' | 'default';
-
-interface TTIMaskReferenceImage {
-  base64: string;
-  mimeType?: string;
-  subjectType?: TTISubjectType;  // defaults to 'default'
-}
 ```
 
 ### TTIResponse

package/dist/middleware/services/tti/providers/base-tti-provider.js

@@ -216,17 +216,6 @@ class BaseTTIProvider {
                     throw new InvalidConfigError(this.providerName, 'maskDilation must be between 0.0 and 1.0');
                 }
             }
-            if (request.maskReferenceImages && request.maskReferenceImages.length > 0) {
-                for (let i = 0; i < request.maskReferenceImages.length; i++) {
-                    const ref = request.maskReferenceImages[i];
-                    if (!ref.base64 || ref.base64.trim().length === 0) {
-                        throw new InvalidConfigError(this.providerName, `maskReferenceImages[${i}] has empty base64 data`);
-                    }
-                }
-            }
-        }
-        if (request.maskReferenceImages && request.maskReferenceImages.length > 0 && !request.baseImage) {
-            throw new InvalidConfigError(this.providerName, 'maskReferenceImages requires baseImage to be set');
         }
         // If reference images are provided, validate them
         if (request.referenceImages && request.referenceImages.length > 0) {

package/dist/middleware/services/tti/providers/google-cloud-provider.js

@@ -565,18 +565,31 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
         try {
             const { client, helpers } = await this.getAiplatformClient(region);
             const endpoint = `projects/${this.config.projectId}/locations/${region}/publishers/google/models/${internalModelId}`;
-            // Build referenceImages array: [RAW base image, MASK image]
+            // Build referenceImages array.
+            //
+            // Vertex AI uses sequential, distinct referenceId values for each entry.
+            // RAW and MASK have separate IDs — the API pairs them by type/order, not by shared ID.
+            // SUBJECT gets the next ID after MASK and MUST be cited in the prompt as [N].
+            //
+            // Correct layout (confirmed by official Vertex AI docs):
+            //   REFERENCE_TYPE_RAW    referenceId: 1
+            //   REFERENCE_TYPE_MASK   referenceId: 2
+            //   REFERENCE_TYPE_SUBJECT referenceId: 3  ← referenced in prompt as [3]
+            //
+            // See: https://cloud.google.com/vertex-ai/generative-ai/docs/image/edit-insert-objects
+            const RAW_REFERENCE_ID = 1;
+            const MASK_REFERENCE_ID = 2;
             const referenceImages = [
                 {
                     referenceType: 'REFERENCE_TYPE_RAW',
-                    referenceId: 1,
+                    referenceId: RAW_REFERENCE_ID,
                     referenceImage: {
                         bytesBase64Encoded: request.baseImage.base64,
                     },
                 },
                 {
                     referenceType: 'REFERENCE_TYPE_MASK',
-                    referenceId: 2,
+                    referenceId: MASK_REFERENCE_ID,
                     referenceImage: {
                         bytesBase64Encoded: request.maskImage.base64,
                     },
@@ -586,23 +599,6 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                     },
                 },
             ];
-            // Append optional subject reference images for guided inpainting
-            if (request.maskReferenceImages && request.maskReferenceImages.length > 0) {
-                for (const [i, ref] of request.maskReferenceImages.entries()) {
-                    const subjectType = GoogleCloudTTIProvider.SUBJECT_TYPE_MAP[ref.subjectType ?? 'default'] ??
-                        'SUBJECT_TYPE_DEFAULT';
-                    referenceImages.push({
-                        referenceType: 'REFERENCE_TYPE_SUBJECT',
-                        referenceId: 3 + i,
-                        referenceImage: {
-                            bytesBase64Encoded: ref.base64,
-                        },
-                        subjectImageConfig: {
-                            subjectType,
-                        },
-                    });
-                }
-            }
             const instanceValue = {
                 prompt: request.prompt,
                 referenceImages,
@@ -832,7 +828,8 @@ GoogleCloudTTIProvider.EDIT_MODE_MAP = {
 };
 GoogleCloudTTIProvider.SUBJECT_TYPE_MAP = {
     person: 'SUBJECT_TYPE_PERSON',
-    animal: 'SUBJECT_TYPE_ANIMAL',
+    // Vertex AI API uses ANIMAL_COMPANION, not ANIMAL
+    animal: 'SUBJECT_TYPE_ANIMAL_COMPANION',
     product: 'SUBJECT_TYPE_PRODUCT',
     default: 'SUBJECT_TYPE_DEFAULT',
 };

package/dist/middleware/types/index.d.ts

@@ -82,30 +82,6 @@ export interface TTIReferenceImage {
     /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
     mimeType?: string;
 }
-/**
- * Subject type hint for mask reference images.
- * Helps the model understand what kind of subject is shown in the reference image.
- * - 'person'  — a human character
- * - 'animal'  — an animal or creature
- * - 'product' — an object, product, or item
- * - 'default' — let the model decide (fallback)
- */
-export type TTISubjectType = 'person' | 'animal' | 'product' | 'default';
-/**
- * Reference image for mask-based inpainting (subject reference).
- * Used with maskReferenceImages to guide what the model inserts into the masked area.
- */
-export interface TTIMaskReferenceImage {
-    /** Base64-encoded image data of the subject to insert */
-    base64: string;
-    /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
-    mimeType?: string;
-    /**
-     * Subject type hint for the model.
-     * Defaults to 'default' if omitted.
-     */
-    subjectType?: TTISubjectType;
-}
 /**
  * Unified TTI generation request
  * Works for both simple text-to-image and character consistency
@@ -153,14 +129,6 @@ export interface TTIRequest {
      * - 'outpainting': extend image beyond its boundaries into the masked area
      */
     editMode?: 'inpainting-insert' | 'inpainting-remove' | 'background-swap' | 'outpainting';
-    /**
-     * Optional subject reference images for mask-based inpainting.
-     * Only valid when baseImage and maskImage are set.
-     * Each entry guides the model to insert a specific subject into the masked area
-     * (e.g., "place the character from this reference image into the mask").
-     * Only supported by the 'imagen-capability' model.
-     */
-    maskReferenceImages?: TTIMaskReferenceImage[];
     /** Additional provider-specific options */
     providerOptions?: Record<string, unknown>;
     /**

package/package.json

@@ -1,90 +1,90 @@
-{
-  "name": "@loonylabs/tti-middleware",
-  "version": "1.11.0",
-  "description": "Provider-agnostic Text-to-Image middleware with GDPR compliance. Supports Google Cloud (Imagen, Gemini), Eden AI, and IONOS.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md",
-    ".env.example"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "npm run test:unit",
-    "test:unit": "jest --testPathPattern=tests/unit",
-    "test:unit:watch": "jest --testPathPattern=tests/unit --watch",
-    "test:unit:coverage": "jest --testPathPattern=tests/unit --coverage",
-    "test:integration": "cross-env TTI_INTEGRATION_TESTS=true jest --testPathPattern=tests/integration",
-    "test:ci": "jest --runInBand --ci --coverage --testPathPattern=tests/unit",
-    "test:live": "TTI_INTEGRATION_TESTS=true jest tests/integration/*.integration.test.ts --testTimeout=120000",
-    "test:manual": "ts-node scripts/manual-test-edenai.ts",
-    "test:manual:google-cloud": "ts-node scripts/manual-test-google-cloud.ts",
-    "lint": "eslint src/**/*.ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run clean && npm run build && npm run test"
-  },
-  "keywords": [
-    "tti",
-    "text-to-image",
-    "image-generation",
-    "ai",
-    "vertex-ai",
-    "google-cloud",
-    "gemini",
-    "imagen",
-    "middleware",
-    "provider-agnostic",
-    "typescript",
-    "gdpr",
-    "dsgvo",
-    "character-consistency"
-  ],
-  "author": "loonylabs-dev",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/loonylabs-dev/tti-middleware.git"
-  },
-  "bugs": {
-    "url": "https://github.com/loonylabs-dev/tti-middleware/issues"
-  },
-  "homepage": "https://github.com/loonylabs-dev/tti-middleware#readme",
-  "peerDependencies": {
-    "@google-cloud/aiplatform": ">=3.0.0",
-    "@google/genai": ">=1.40.0"
-  },
-  "peerDependenciesMeta": {
-    "@google-cloud/aiplatform": {
-      "optional": true
-    },
-    "@google/genai": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@google-cloud/aiplatform": "^3.29.0",
-    "@google/genai": "^1.40.0",
-    "@types/jest": "^29.5.8",
-    "@types/node": "^20.10.0",
-    "@typescript-eslint/eslint-plugin": "^6.13.0",
-    "@typescript-eslint/parser": "^6.13.0",
-    "cross-env": "^10.1.0",
-    "dotenv": "^17.2.3",
-    "eslint": "^8.54.0",
-    "jest": "^29.7.0",
-    "prettier": "^3.1.0",
-    "ts-jest": "^29.1.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.3.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@loonylabs/tti-middleware",
+  "version": "1.12.0",
+  "description": "Provider-agnostic Text-to-Image middleware with GDPR compliance. Supports Google Cloud (Imagen, Gemini), Eden AI, and IONOS.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run test:unit",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:unit:watch": "jest --testPathPattern=tests/unit --watch",
+    "test:unit:coverage": "jest --testPathPattern=tests/unit --coverage",
+    "test:integration": "cross-env TTI_INTEGRATION_TESTS=true jest --testPathPattern=tests/integration",
+    "test:ci": "jest --runInBand --ci --coverage --testPathPattern=tests/unit",
+    "test:live": "TTI_INTEGRATION_TESTS=true jest tests/integration/*.integration.test.ts --testTimeout=120000",
+    "test:manual": "ts-node scripts/manual-test-edenai.ts",
+    "test:manual:google-cloud": "ts-node scripts/manual-test-google-cloud.ts",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "keywords": [
+    "tti",
+    "text-to-image",
+    "image-generation",
+    "ai",
+    "vertex-ai",
+    "google-cloud",
+    "gemini",
+    "imagen",
+    "middleware",
+    "provider-agnostic",
+    "typescript",
+    "gdpr",
+    "dsgvo",
+    "character-consistency"
+  ],
+  "author": "loonylabs-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/loonylabs-dev/tti-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loonylabs-dev/tti-middleware/issues"
+  },
+  "homepage": "https://github.com/loonylabs-dev/tti-middleware#readme",
+  "peerDependencies": {
+    "@google-cloud/aiplatform": ">=3.0.0",
+    "@google/genai": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/aiplatform": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google-cloud/aiplatform": "^3.29.0",
+    "@google/genai": "^1.40.0",
+    "@types/jest": "^29.5.8",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "cross-env": "^10.1.0",
+    "dotenv": "^17.2.3",
+    "eslint": "^8.54.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}