Skip to main content
This guide shows you how to edit an existing image through the AI Studio image endpoint. There is no separate edit endpoint: you send the image (or images) you want to change as referenceImageUrls together with an instruction, and the model returns a new image. The same request shape covers replacing objects, changing backgrounds, restyling, and combining elements from several pictures.

What You Will Build

Targeted Changes

Replace, remove, or add an element while keeping the rest of the picture

Restyling

Turn a photo into an illustration, a sketch, or a different look

Composition

Combine a subject from one image with the setting of another

Consistent Outputs

Produce variations of a product shot that keep the product identical

Before You Begin

Make sure you have:
  • A Pictory API key
  • Node.js or Python installed on your machine
  • The required packages installed
  • Publicly accessible URLs for the images you want to edit

Which Models Can Edit

flux-schnell cannot edit. Sending reference images to it returns a 400 with the code IMAGE_EDITING_NOT_SUPPORTED. The Get Model Capabilities endpoint reports editing and referenceImages.max per model.

Step-by-Step Guide

Step 1: Set Up Your Request

Send the image to edit as the first reference and write the instruction as the prompt. For a plain edit, one reference is enough. To bring in an element from another picture, add it as a second reference and refer to it by position in the prompt.
Edits are sent verbatim by default, which suits a precise instruction such as “replace X with Y”: the enhancer is designed to make creative prompts richer and can add detail you did not ask for. Set enhancePrompt: true when you want the model to interpret a loose brief.

Step 2: Submit the Image Generation Request

Send the request to the AI Studio image generation endpoint.

Step 3: Poll for the Result

Check the job status at regular intervals until the edited image is ready.

Understanding the Parameters

Common Edits

Tips for Editing

  • Say what stays. Models change more than you ask unless told otherwise. “Keep the background, lighting, and framing unchanged” is worth the words.
  • Refer to images by position. “The first image”, “the second image” maps to the order of referenceImageUrls.
  • Match the aspect ratio. On models that honor aspectRatio for edits, send the source image’s ratio unless you want a crop or extension.
  • Chain edits. The edited image’s URL can be the reference for the next edit, so complex changes can be done in small, controllable steps.

Next Steps