ImagineoAI JavaScript SDK

A universal JavaScript/TypeScript SDK for interacting with the ImagineoAI API from both browser and Node.js environments.

• Dual entrypoint: Environment-specific bundles for browser and Node.js
• Type-safe: All API types and schemas are shared and validated
• Modern: ESM, strict types, async/await, and universal fetch
• Image Operations: Generate, upscale, and inpaint images with a unified API
• AI Models: Support for Gemini 2.5, Nanobanana, Flux, OpenAI, and more
• Cloudinary AI: Advanced object removal, background removal, and extraction
• Multimodal: Combine up to 10 images with intelligent AI blending
• Smart Batch: AI-powered batch generation of 20+ creative variations from a single image

Installation

bun add @imagineoai/javascript-sdk
# or
npm install @imagineoai/javascript-sdk

Usage

Describe a Run's Image

import { ImagineoAIClient } from 'imagineoai-javascript-sdk/server';

const client = new ImagineoAIClient('https://api.imagineo.ai', { apiKey: 'YOUR_API_KEY' });

const result = await client.describe({
  run_id: '123e4567-e89b-12d3-a456-426614174000',
  model: 'llava13b', // or 'clip', optional
});

console.log(result.replicate_output);

Browser

import { ImagineoAIClient, upload } from "@imagineoai/javascript";

const client = new ImagineoAIClient("https://api.imagineoai.com", { apiKey: "sk-..." });

const file = new File([/* ... */], "image.png");
const result = await client.uploadImage({ file });

Node.js

import { ImagineoAIClient, upload } from "@imagineoai/javascript/server";
import fs from "fs";

const client = new ImagineoAIClient("https://api.imagineoai.com", { apiKey: "sk-..." });

const buffer = fs.readFileSync("./image.png");
const result = await client.uploadImage({ file: buffer });

API Reference

ImagineoAIClient

Constructor

new ImagineoAIClient(apiUrl: string, authOptions?: ImagineoAIClientAuthOptions, options?: { debug: boolean })

• apiUrl: The base URL of the ImagineoAI API
• authOptions: { apiKey: string } or { getToken: () => Promise<string> }
• options: { debug: boolean } (optional)

Methods

• uploadImage(input: UploadImageRequest): Promise<UploadImageResponse>
  • Uploads an image file (browser: File/Blob, Node: Buffer/Readable)
  • Supports parent_id to link uploads to existing runs
  • Example:

    const result = await client.images.upload({
      file: imageFile,
      description: 'My edited image',
      parent_id: 'original-run-uuid' // Links to parent run
    });

• upscale(input: UpscaleImageInput): Promise<GenerateImageOutput>
  • Upscales an existing image using a supported model.
  • Example:

    const result = await client.images.upscale({
      original_run_id: '...',
      upscale_factor: 2,
      use_original_prompt: true
    });

• inpaint(input: InpaintImageInput): Promise<GenerateImageOutput>
  • Inpaints an image using a mask and (optionally) a prompt or original run.
  • Example:

    const result = await client.images.inpaint({
      mask_image_url: 'https://.../mask.png',
      image_url: 'https://.../input.png',
      prompt: 'remove the background'
    });

• getRun(runId: string): Promise<RunRelatedResponse>
  • Fetches details for a specific run, including its associated jobs.
  • Example:

    const runDetails = await client.images.getRun('your-run-id');
    console.log(runDetails.data.jobs); // Array of job objects associated with the run

• getRunJobs(runId: string): Promise<RunJobsListResponse>
  • Fetches all jobs specifically associated with a given run ID.
  • Example:

    const jobsList = await client.images.getRunJobs('your-run-id');
    console.log(jobsList.data); // Array of job objects

• backgroundRemove(input: BackgroundRemoveRequest): Promise<BackgroundRemoveResponse>
  • Removes background from an image using Cloudinary AI
  • Automatically tracks parent-child relationships when using run_id
  • Example:

    // Using run_id (automatically sets parent_run_id)
    const result = await client.images.backgroundRemove({
      run_id: 'existing-run-uuid' // Parent run is tracked automatically
    });
        
    // Using direct image URL
    const result = await client.images.backgroundRemove({
      image_url: 'https://example.com/image.jpg'
    });

• smartBatch.json(input: SmartBatchRequest): Promise<SmartBatchResponse>
  • Generate 20+ AI-powered creative variations from a single image
  • Supports automatic creative brief generation or user-guided prompts
  • Example:

    // Automatic creative generation
    const batch = await client.images.smartBatch.json({
      image_id: 'existing-run-id',
      variation_count: 20
    });
        
    // With enhanced user prompt
    const batch = await client.images.smartBatch.json({
      image_url: 'https://example.com/source.jpg',
      prompt: 'cyberpunk style',
      enhance_prompt: true,
      variation_count: 25
    });
        
    // Check status
    const status = await client.images.smartBatch.getStatus(batch.batch_id);
    console.log(`Progress: ${status.completed_variations}/${status.total_variations}`);

• generativeRemove(input: GenerativeRemoveRequest): Promise<GenerativeRemoveResponse>
  • Removes specified objects from images using Cloudinary's generative AI
  • Example:

    const result = await client.images.genRemove({
      run_id: 'existing-run-uuid',
      prompt: 'people', // What to remove
      remove_shadow: true,
      multiple: true // Remove all instances
    });

• extract(input: ExtractRequest): Promise<ExtractResponse>
  • Extracts specific objects from images using Cloudinary AI
  • Example:

    const result = await client.images.extract({
      run_id: 'existing-run-uuid',
      prompt: 'cat', // What to extract
      multiple: false // Extract single instance
    });

Gemini 2.5 Features

• Generate with Gemini 2.5:

  const result = await client.images.generate({
    prompt: "A futuristic cityscape",
    model_type: "gemini-2.5",
    aspect_ratio: "16:9"
  });

• Combine Images with Gemini 2.5:

  const result = await client.images.combine.gemini25.json({
    prompt: "Blend these into a cohesive scene",
    run_ids: ["run1", "run2", "run3"],
    aspect_ratio: "1:1"
  });

• Edit with Gemini 2.5:

  const result = await client.images.edit.gemini25.json({
    prompt: "Add a sunset sky",
    original_run_id: "run123",
    mask_url: "https://example.com/mask.png",
    aspect_ratio: "16:9"
  });

  • Example:

    const result = await client.images.extract({
      run_id: 'existing-run-uuid',
      prompt: 'car', // What to extract
      mode: 'content', // or 'mask'
      preserve_alpha: true
    });

• reframe(input: ReframeRequest): Promise<ReframeResponse>

  • Reframes images to different aspect ratios using Luma AI
  • Automatically tracks parent-child relationships when using run_id
  • Example:

    // JSON method
    const result = await client.images.reframe.json({
      run_id: 'existing-run-uuid', // Automatically becomes the parent
      prompt: 'Expand the scene naturally',
      aspect_ratio: '16:9',
      model: 'photon-flash-1'
    });
        
    // FormData method (for file uploads)
    const result = await client.images.reframe.formData({
      image_file: imageFile,
      prompt: 'Reframe to square',
      aspect_ratio: '1:1'
    });

Standalone Upload

• upload(input: UploadImageRequest): Promise<UploadImageResponse>
  • (Browser: from @imagineoai/javascript-sdk)
  • (Node: from @imagineoai/javascript-sdk/server)

Types

• ImagineoAIClientAuthOptions: { apiKey: string } | { getToken: () => Promise<string> }
• UploadImageRequest: { file: File | Blob | Buffer | Readable, description?: string, parent_id?: string }
• UploadImageResponse: { image_url: string; run_id: string; created_at: string; parent_id?: string }
• BackgroundRemoveRequest: { image_url?: string; run_id?: string }
• BackgroundRemoveResponse: { url: string; runId: string; parentRunId?: string }
• GenerativeRemoveRequest: { image_url?: string; run_id?: string; prompt: string; remove_shadow?: boolean; multiple?: boolean }
• GenerativeRemoveResponse: { url: string; runId: string; parentRunId?: string }
• ExtractRequest: { image_url?: string; run_id?: string; prompt: string; mode?: 'content' | 'mask'; preserve_alpha?: boolean; multiple?: boolean; invert?: boolean }
• ExtractResponse: { url: string; runId: string; parentRunId?: string }
• ReframeRequest: { prompt: string; image_url?: string; run_id?: string; aspect_ratio?: string; model?: 'photon-flash-1' | 'photon-1'; [positioning props] } (run_id automatically becomes parent)
• ReframeFormDataRequest: Similar to ReframeRequest but accepts image_file for direct file uploads
• RunRelatedResponse: An object containing run details, including an array of associated jobs within its data property.
• RunJobsListResponse: An object containing an array of Job objects within its data property.

Parent-Child Relationship Tracking

The SDK supports tracking relationships between images through the parent_id field. This helps maintain image lineage across operations:

Automatic Parent Tracking

When using run_id with operations like background removal and reframe, the parent relationship is automatically established:

// Original image has run_id: 'abc-123'

// Background removal
const bgRemoved = await client.images.backgroundRemove({
  run_id: 'abc-123' // This becomes the parent
});
// bgRemoved.parentRunId === 'abc-123'

// Reframe
const reframed = await client.images.reframe.json({
  run_id: 'abc-123', // This becomes the parent
  prompt: 'Expand to 16:9',
  aspect_ratio: '16:9'
});
// reframed.parent_id === 'abc-123'

Manual Parent Tracking

For upload operations, you can manually specify the parent:

// Upload with parent
const upload = await client.images.upload({
  file: editedImage,
  parent_id: 'original-run-uuid'
});

Use Cases

• Track editing history and image derivations
• Build image family trees
• Maintain audit trails for generated content
• Link variations back to originals

Environment-specific Details

• Browser: Uses native fetch and FormData. Only accepts File or Blob for uploads.
• Node.js: Uses formdata-node and undici for fetch and form uploads. Accepts Buffer or Readable streams.

Shared Utilities

• getAuthHeader(authOptions): Returns the correct Authorization header for API key or token-based auth.
• validateUploadInput(input): Throws if the upload input is invalid.

Development

• All shared types are in src/types.ts.
• Shared helpers in src/shared/.
• Environment-specific implementations in src/browser/ and src/server/.

License

MIT