images.edit.fluxKontext

Edit images using the Flux Kontext Max model, which provides high-quality image editing based on text prompts and a reference image from a previous run.

Signatures:

// JSON payload method
client.images.edit.fluxKontext.json(input: FluxKontextEditRequest): Promise<FluxKontextEditResponse>

// FormData method
client.images.edit.fluxKontext.formData(input: FluxKontextEditFormDataRequest): Promise<FluxKontextEditResponse>

JSON Method

Use this method when you have a run_id from a previous image generation and want to edit that image with Flux Kontext Max.

Parameters

• input: FluxKontextEditRequest
  • original_run_id: string - UUID of the original run containing the source image (required)
  • prompt: string - Text description of the desired changes (required)
  • aspect_ratio?: string - Aspect ratio for the edited image (optional, defaults to "match_input_image")
  • seed?: number - Random seed for reproducible results (optional)
  • model: "flux-kontext-max" - Model type (automatically set)
  • sync?: boolean - If true, run synchronously and return completed result immediately. If false (default), run asynchronously with webhook processing (optional)

Returns

• FluxKontextEditResponse - Contains the edited image details and status
• Throws: On validation, network, or API error

Example (JSON)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Asynchronous edit (default) - returns immediately with pending status
const asyncResult = await client.images.edit.fluxKontext.json({
  original_run_id: '123e4567-e89b-12d3-a456-426614174000',
  prompt: 'Change the sky to a vibrant sunset with orange and pink clouds',
  aspect_ratio: '16:9', // Optional, defaults to "match_input_image"
  seed: 42, // Optional, for reproducible results
  sync: false // Default - async operation
});

console.log('Async Edit run ID:', asyncResult.run_id);
console.log('Status:', asyncResult.live_status); // 'pending'
// Poll or use webhooks to check when processing is complete

// Synchronous edit - waits for completion and returns final result
const syncResult = await client.images.edit.fluxKontext.json({
  original_run_id: '123e4567-e89b-12d3-a456-426614174000',
  prompt: 'Add a wooden bridge across the river',
  aspect_ratio: 'match_input_image',
  seed: 123,
  sync: true // Synchronous operation
});

console.log('Sync Edit run ID:', syncResult.run_id);
console.log('Status:', syncResult.live_status); // 'completed'
console.log('Final image URL:', syncResult.image_url); // Available immediately

FormData Method

Use this method when you prefer to send data as form data, which can be useful in certain environments or for specific integrations.

Parameters

• input: FluxKontextEditFormDataRequest
  • original_run_id: string - UUID of the original run containing the source image
  • prompt: string - Text description of the desired changes
  • aspect_ratio?: string - Aspect ratio for the edited image (optional)
  • seed?: number - Random seed for reproducible results (optional)
  • model?: "flux-kontext-max" - Model type (optional, defaults to "flux-kontext-max")
  • sync?: boolean - If true, run synchronously and return completed result immediately (optional, defaults to false)

Example (FormData)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Asynchronous FormData edit
const asyncResult = await client.images.edit.fluxKontext.formData({
  original_run_id: '123e4567-e89b-12d3-a456-426614174000',
  prompt: 'Add a rainbow in the background',
  aspect_ratio: '1:1',
  seed: 123,
  sync: false // Default - async operation
});

console.log('Async Edit run ID:', asyncResult.run_id);
console.log('Status:', asyncResult.live_status); // 'pending'

// Synchronous FormData edit
const syncResult = await client.images.edit.fluxKontext.formData({
  original_run_id: '123e4567-e89b-12d3-a456-426614174000',
  prompt: 'Transform the scene to winter with snow',
  aspect_ratio: '16:9',
  seed: 456,
  sync: true // Synchronous operation
});

console.log('Sync Edit run ID:', syncResult.run_id);
console.log('Status:', syncResult.live_status); // 'completed'
console.log('Final image URL:', syncResult.image_url); // Available immediately

Synchronous vs Asynchronous Operations

Flux Kontext Max editing supports both synchronous and asynchronous processing modes:

Asynchronous Mode (Default: sync: false)

• Use Case: Recommended for production applications and long-running edits
• Behavior: Returns immediately with live_status: 'pending'
• Advantages:
  • Non-blocking operation - your application remains responsive
  • Supports webhook notifications for completion
  • Better for handling multiple concurrent requests
• Processing: Monitor progress via polling or webhooks
• Response: image_url will be null initially, populated once processing completes

Synchronous Mode (sync: true)

• Use Case: Suitable for immediate results or testing scenarios
• Behavior: Waits for the edit to complete before returning
• Advantages:
  • Immediate results - no need for polling or webhooks
  • Simpler integration for basic use cases
• Considerations:
  • Longer response times (typically 10-30 seconds)
  • Blocking operation - may cause timeouts in some environments
  • Less suitable for high-traffic applications
• Response: image_url available immediately in the response

// Choose based on your use case:

// For production applications with webhook handling:
const asyncEdit = await client.images.edit.fluxKontext.json({
  original_run_id: 'run-id',
  prompt: 'Your edit prompt',
  sync: false // or omit (default)
});

// For immediate results in testing or simple applications:
const syncEdit = await client.images.edit.fluxKontext.json({
  original_run_id: 'run-id', 
  prompt: 'Your edit prompt',
  sync: true
});

Aspect Ratio Options

Flux Kontext Max editing supports the following aspect ratios:

• Standard ratios: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "9:21", "2:1", "1:2"
• Special option: "match_input_image" - Automatically matches the aspect ratio of the source image (default)

Response Format

Both methods return a FluxKontextEditResponse with the following structure:

{
  run_id: string;           // UUID of the new edit run
  user_id: string;          // User identifier
  created_at: string;       // ISO timestamp
  updated_at: string;       // ISO timestamp  
  image_url: string | null; // URL of edited image (null while processing)
  inputs: any;              // Input parameters used
  live_status: string | null; // Current processing status
  status: string;           // Run status
  progress: number;         // Progress indicator (0-1)
  run_type: string;         // Type of run
  parent_run_id?: string;   // Reference to original run
}

Workflow Example

Here's a complete workflow showing image generation followed by editing:

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Step 1: Generate an initial image
const generation = await client.images.generate({
  prompt: 'A serene mountain landscape with a lake',
  model_type: 'flux-kontext-max',
  aspect_ratio: '16:9'
});

if (generation?.data?.run_id) {
  console.log('Generated image:', generation.data.image_url);
  
  // Step 2: Edit the generated image
  const edit = await client.images.edit.fluxKontext.json({
    original_run_id: generation.data.run_id,
    prompt: 'Add a wooden cabin by the lake shore with smoke coming from the chimney',
    aspect_ratio: 'match_input_image' // Keep same aspect ratio
  });
  
  console.log('Edit started:', edit.run_id);
  console.log('Edit status:', edit.live_status);
  
  // The edited image will be available at edit.image_url once processing completes
}

Notes

• Asynchronous Processing: Flux Kontext Max editing is processed asynchronously. The initial response will have live_status: 'pending' or 'processing', and you should poll the run status or use webhooks to know when the edit is complete.

• Parent-Child Relationship: The edit run maintains a reference to the original run via parent_run_id, creating a traceable editing history.

• Quality: Flux Kontext Max provides high-quality image editing with excellent preservation of the original image's style and content while incorporating the requested changes.

• Model Routing: The API automatically routes to the Flux Kontext Max editing service based on the model parameter.

• Validation: All inputs are validated using Zod schemas before sending to the API.

See the API Reference for complete type definitions and additional details.