Image editing

Modify existing images with natural language instructions. Describe the edit you want and the uni-1 family applies it while preserving the parts of the image you did not mention. For generating new images from text, see Image generation.

Image editing works with both uni-1 and uni-1-max — same parameters, same wire format. Pass "model": "uni-1-max" for higher-quality output. See Models.

When to use image editing

Use type: "image_edit" when you have an existing image and want to modify it. Use type: "image" with image_ref when you want to create something new inspired by a reference.

Scenario	Use	Why
Change a photo’s background	image_edit + source	Keeps the subject, only changes the background
Convert a photo to manga style	image_edit + source + style: "manga"	Transforms the existing image
Create a new image in a similar style	image + image_ref	Generates something new using the reference for style guidance
Combine elements from multiple images	image + image_ref (multiple)	Compositing, not editing a single source

Basic request

An image edit requires three things: type set to "image_edit", a source image, and a prompt describing the edit.

Python

from luma_agents import Luma

client = Luma()

generation = client.generations.create(
    type="image_edit",
    prompt="Change the sky to a dramatic sunset with orange and purple clouds",
    source={"url": "https://example.com/landscape.jpg"},
)

TypeScript

import Luma from "luma-agents";

const client = new Luma();

const generation = await client.generations.create({
  type: "image_edit",
  prompt: "Change the sky to a dramatic sunset with orange and purple clouds",
  source: { url: "https://example.com/landscape.jpg" },
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Type:   lumaagents.F(lumaagents.GenerationNewParamsTypeImageEdit),
    Prompt: lumaagents.F("Change the sky to a dramatic sunset with orange and purple clouds"),
    Source: lumaagents.F(lumaagents.GenerationNewParamsSource{
        URL: lumaagents.F("https://example.com/landscape.jpg"),
    }),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image_edit",
    "prompt": "Change the sky to a dramatic sunset with orange and purple clouds",
    "source": {
      "url": "https://example.com/landscape.jpg"
    }
  }'

CLI

luma-agents-cli generations create \
  --type image_edit \
  --prompt "Change the sky to a dramatic sunset with orange and purple clouds" \
  --source-url "https://example.com/landscape.jpg"

Source image

The source field accepts a single image — either as a URL or inline base64 data.

From a URL:

{
  "source": {
    "url": "https://example.com/photo.jpg"
  }
}

From base64 data:

{
  "source": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
    "media_type": "image/jpeg"
  }
}

The source field is required for image_edit and rejected for image type requests. Provide either url or data — not both. URLs must be publicly accessible. Base64 images require media_type. Maximum image size is 50 MB.

Style transfer with style

Combine source with the style parameter to apply a style preset to an existing image:

Python

generation = client.generations.create(
    type="image_edit",
    prompt="Convert to a bold manga illustration with clean ink outlines and vivid flat colors",
    source={"url": "https://example.com/photograph.jpg"},
    style="manga",
)

TypeScript

const generation = await client.generations.create({
  type: "image_edit",
  prompt: "Convert to a bold manga illustration with clean ink outlines and vivid flat colors",
  source: { url: "https://example.com/photograph.jpg" },
  style: "manga",
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Type:   lumaagents.F(lumaagents.GenerationNewParamsTypeImageEdit),
    Prompt: lumaagents.F("Convert to a bold manga illustration with clean ink outlines and vivid flat colors"),
    Source: lumaagents.F(lumaagents.GenerationNewParamsSource{
        URL: lumaagents.F("https://example.com/photograph.jpg"),
    }),
    Style: lumaagents.F(lumaagents.GenerationNewParamsStyleManga),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image_edit",
    "prompt": "Convert to a bold manga illustration with clean ink outlines and vivid flat colors",
    "source": {"url": "https://example.com/photograph.jpg"},
    "style": "manga"
  }'

Using reference images with edits

Combine source (the image to edit) with image_ref (style/content references) to guide the edit. Up to 8 reference images are supported.

Single reference — apply a color grading from a reference:

Python

generation = client.generations.create(
    type="image_edit",
    prompt="Apply the color grading from the reference to the source image",
    source={"url": "https://example.com/my-photo.jpg"},
    image_ref=[
        {"url": "https://example.com/color-reference.jpg"},
    ],
)

TypeScript

const generation = await client.generations.create({
  type: "image_edit",
  prompt: "Apply the color grading from the reference to the source image",
  source: { url: "https://example.com/my-photo.jpg" },
  image_ref: [{ url: "https://example.com/color-reference.jpg" }],
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Type:   lumaagents.F(lumaagents.GenerationNewParamsTypeImageEdit),
    Prompt: lumaagents.F("Apply the color grading from the reference to the source image"),
    Source: lumaagents.F(lumaagents.GenerationNewParamsSource{
        URL: lumaagents.F("https://example.com/my-photo.jpg"),
    }),
    ImageRef: lumaagents.F([]lumaagents.GenerationNewParamsImageRef{
        {URL: lumaagents.F("https://example.com/color-reference.jpg")},
    }),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image_edit",
    "prompt": "Apply the color grading from the reference to the source image",
    "source": {"url": "https://example.com/my-photo.jpg"},
    "image_ref": [{"url": "https://example.com/color-reference.jpg"}]
  }'

Multiple references — combine lighting from one and texture from another:

Python

generation = client.generations.create(
    type="image_edit",
    prompt="Apply the lighting from the first reference and the texture from the second to the source image",
    source={"url": "https://example.com/my-photo.jpg"},
    image_ref=[
        {"url": "https://example.com/lighting-reference.jpg"},
        {"url": "https://example.com/texture-reference.jpg"},
    ],
)

TypeScript

const generation = await client.generations.create({
  type: "image_edit",
  prompt:
    "Apply the lighting from the first reference and the texture from the second to the source image",
  source: { url: "https://example.com/my-photo.jpg" },
  image_ref: [
    { url: "https://example.com/lighting-reference.jpg" },
    { url: "https://example.com/texture-reference.jpg" },
  ],
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Type:   lumaagents.F(lumaagents.GenerationNewParamsTypeImageEdit),
    Prompt: lumaagents.F("Apply the lighting from the first reference and the texture from the second to the source image"),
    Source: lumaagents.F(lumaagents.GenerationNewParamsSource{
        URL: lumaagents.F("https://example.com/my-photo.jpg"),
    }),
    ImageRef: lumaagents.F([]lumaagents.GenerationNewParamsImageRef{
        {URL: lumaagents.F("https://example.com/lighting-reference.jpg")},
        {URL: lumaagents.F("https://example.com/texture-reference.jpg")},
    }),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image_edit",
    "prompt": "Apply the lighting from the first reference and the texture from the second to the source image",
    "source": {"url": "https://example.com/my-photo.jpg"},
    "image_ref": [
      {"url": "https://example.com/lighting-reference.jpg"},
      {"url": "https://example.com/texture-reference.jpg"}
    ]
  }'

When using multiple references, always label each reference’s role in the prompt: “Apply the lighting from the first reference and the texture from the second.” Without explicit labels, the model guesses which aspects to pull from each image.

Common edit types

Object modification

Change colors, materials, or properties of objects in the image:

generation = client.generations.create(
    type="image_edit",
    prompt="Change the car's color to midnight blue with a metallic finish",
    source={"url": "https://example.com/car-photo.jpg"},
)

Background replacement

Replace the background while preserving the subject:

generation = client.generations.create(
    type="image_edit",
    prompt="Replace the background with a tropical beach at sunset, "
           "warm golden light matching the direction of light on the subject",
    source={"url": "https://example.com/portrait.jpg"},
)

Lighting adjustment

Change the lighting or time of day:

generation = client.generations.create(
    type="image_edit",
    prompt="Change the lighting to dramatic golden hour with long shadows from the left",
    source={"url": "https://example.com/scene.jpg"},
)

Be specific about what to change and what to preserve. “Replace the background with a tropical beach” is better than “make it look tropical.” For complex edits (background + color + style), do them as separate sequential operations for more predictable results.

Validation rules

These constraints are specific to image_edit requests. General constraints from Image generation also apply.

Rule	Constraint
type	Must be "image_edit"
source	Required. Must provide url or data — not both
source.url	Must be publicly accessible. Max 50 MB
source.data	Must be valid base64. Requires media_type
image_ref	Optional. Up to 8 additional reference images
prompt	Required. 1–6,000 characters describing the desired edit

Common validation errors:

Mistake	HTTP code	Error
Missing source	400	"source is required for type 'image_edit'"
Providing source with type: "image"	400	"source is only valid for type 'image_edit'"
source with both url and data	400	"source: provide either 'url' or 'data', not both"
source.data without media_type	400	"source: 'media_type' is required with 'data'"
source image over 50 MB	413	"source: image exceeds 50 MB limit"
Unreachable source.url	422	"source: failed to fetch URL"
Invalid source.data	422	"source: invalid base64 data"

Response

The response format is identical to image generation — poll GET /v1/generations/{id} until the state reaches completed or failed.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "image_edit",
  "state": "completed",
  "model": "uni-1",
  "created_at": "2026-04-08T12:00:00Z",
  "output": [
    {
      "type": "image",
      "url": "https://storage.example.com/generations/a1b2c3d4/output.png?X-Amz-Expires=3600&..."
    }
  ],
  "failure_reason": null,
  "failure_code": null
}

Full example

The submit-poll-download workflow for image editing is identical to image generation — set type: "image_edit" and include a source image. See the Quickstart for the complete polling pattern.

Next steps

• Image generation — Generate new images from text
• Models — Model capabilities and limitations
• Pricing — Pay-as-you-go and Provisioned Throughput plans
• Error handling — Every error code with troubleshooting steps
• FAQ — Quick answers to common questions
• API Reference — Complete endpoint specifications