> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Image Editor API

> Edit and modify images with AI-powered tools for comprehensive image manipulation.

export const ToolSection = ({type = "image", outputs = [], title = "", productSlug = "", apiSlug = ""}) => <>
    <CardGroup cols={2}>
      <Card title={`${title} API reference`} icon="webhook" horizontal href={`/api-reference/${type}-projects/${apiSlug}`}>
        Request fields, responses, and examples
      </Card>
      <Card title="API quickstart" icon="forward-fast" horizontal href="/get-started/quick-start">
        Install an SDK and complete your first generation
      </Card>
    </CardGroup>

    <p>
      Check <a href="/billing/overview">API pricing</a> and <a href="/api-reference/models">model credit costs</a>, then <a href={`https://magichour.ai/developer?tab=api-keys&ref=docs-tool-${apiSlug}&utm_source=docs&utm_medium=referral&utm_campaign=tools`}>create an API key</a>.
    </p>
    <p>
      To try {title} without code, use the <a href={`https://magichour.ai/products/${productSlug}${productSlug.includes("?") ? "&" : "?"}utm_source=docs&utm_medium=referral&utm_campaign=tools`}>browser tool</a>.
    </p>

    {outputs && outputs.length > 0 && <Tabs>
        {outputs.map((output, idx) => <Tab key={idx} title={`Example Output ${idx + 1}`}>
            <Frame>
              {type === "video" ? <video controls preload="metadata" playsInline className="rounded-lg h-80" src={`${output.src}#t=0.001`} type={`${output.src?.endsWith("mp4") ? 'video/mp4' : "video/webm"}`}>
                </video> : type === "audio" ? <audio controls preload="metadata" className="w-full" src={output.src}>
                  Your browser does not support the audio element.
                </audio> : <img height="320" className="rounded-lg h-80" src={output.src} alt={`${title} example output ${idx + 1}`} />}
            </Frame>
          </Tab>)}
      </Tabs>}

  </>;

## Overview

AI Image Editor provides comprehensive image editing capabilities using AI. Modify, enhance, and transform images with text-based instructions for natural-looking results without manual editing tools.

**Processing:** See recent [typical API-job times](/api-reference/processing-times). Jobs run
asynchronously, and duration varies with the input, selected settings, and queue load.

<ToolSection
  title="AI Image Editor"
  productSlug="ai-image-editor"
  apiSlug="ai-image-editor"
  type="image"
  outputs={[
{
  src: "/get-started/images/aiimageeditorexample1.jpg",
},
{
  src: "/get-started/images/aiimageeditorexample2.png",
},
]}
/>

## How It Works

1. **Upload image** - Provide the image you want to edit
2. **Describe changes** - Use text to specify desired modifications
3. **AI processes** - AI applies edits intelligently
4. **Download result** - Retrieve your edited image

## Use Cases

* **Photo editing** - Quick modifications without manual tools
* **Object removal** - Remove unwanted elements from images
* **Color adjustments** - Change colors and tones
* **Style changes** - Modify image aesthetics
* **Content addition** - Add new elements to images

## Best Practices

### Editing Instructions

<Tip>**Be specific and clear** - Detailed instructions produce more accurate edits.</Tip>

* **Describe precisely** - Specify exact changes wanted
* **One edit at a time** - Better results with focused changes
* **Use descriptive language** - Clear descriptions work best
* **Reference locations** - Specify where changes should occur

### Image Requirements

| Requirement | Details                                                           |
| :---------- | :---------------------------------------------------------------- |
| Resolution  | 512x512 pixels or larger recommended                              |
| Format      | PNG, JPG, JPEG, JFIF, WEBP, HEIC, HEIF, AVIF, JP2, TIFF, TIF, BMP |
| Quality     | Higher quality enables better edits                               |
| Clarity     | Clear images edit more accurately                                 |

## Code Examples

### Basic Image Edit

<CodeGroup>
  ```python Python theme={null}
  from magic_hour import Client
  from os import getenv

  client = Client(token=getenv("MAGIC_HOUR_API_KEY"))

  result = client.v1.ai_image_editor.generate(
      assets={
          "image_file_paths": ["https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png"]
      },
      style={
          "prompt": "Turn this image into studio ghibli style"
      },
      name="Image Editor image",
      wait_for_completion=True,
      download_outputs=True,
      download_directory="."
  )

  if result.status == "complete":
      print(f"✅ Image edit complete!")
      print(f"Downloaded to: {result.downloaded_paths}")
      print(f"Credits charged: {result.credits_charged}")
  else:
      print(f"❌ Job failed with status: {result.status}")
      if result.error:
          print(f"Error: {result.error.code}: {result.error.message}")
  ```

  ```javascript Node.js theme={null}
  import { Client } from "magic-hour";

  const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });

  const result = await client.v1.aiImageEditor.generate(
    {
      assets: {
        imageFilePaths: [
          "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
        ],
      },
      style: {
        prompt: "Change the background to a sunset beach scene",
      },
      name: "Image Editor image",
    },
    {
      waitForCompletion: true,
      downloadOutputs: true,
      downloadDirectory: ".",
    }
  );

  console.log(`Status: ${result.status}`);
  console.log(`Downloaded to: ${result.downloadedPaths}`);
  ```
</CodeGroup>

## Pricing

Cost depends on the `model` you choose:

| Model                | Credits per edit (from) |
| :------------------- | :---------------------- |
| `flux-2-klein`       | 5                       |
| `qwen-edit`          | 10                      |
| `seedream-v4`        | 40                      |
| `gpt-image-2`        | 50                      |
| `nano-banana`        | 50                      |
| `nano-banana-2-lite` | 50                      |
| `seedream-v4.5`      | 50                      |
| `seedream-v5-pro`    | 75                      |
| `nano-banana-2`      | 100                     |
| `nano-banana-pro`    | 150                     |

Higher resolutions can increase the cost — see the `model` parameter in the [API reference](/api-reference/image-projects/ai-image-editor) for supported resolutions and tiers per model.

<Tip>
  **Try this in our Google Colab Cookbook:** [Run this API with sample
  code](https://colab.research.google.com/drive/1NTHL_lr_s-qBJ-mSecSXPzRLi9_V5JiU?usp=sharing). Just
  add your API key.
</Tip>

## API Reference

<Card title="AI Image Editor API Reference" icon="webhook" href="/api-reference/image-projects/ai-image-editor">
  View full API specification
</Card>

## Related Tools

<CardGroup cols={2}>
  <Card title="AI Face Editor" icon="face-smile" href="/tools/image/face-editor">
    Edit facial features specifically
  </Card>

  <Card title="Image Background Remover" icon="eraser" href="/tools/image/background-remover">
    Remove image backgrounds
  </Card>
</CardGroup>