AI Image Editing API — Instruction Edits, Masking, and Reference Inputs

Three Ways to Edit an Image

Muapi's image-editing models fall into three input patterns. Instruction edits take a source image_url (or several, via images_list) plus a text prompt describing the change — "make the sky sunset orange," "add a hat," "combine these two product shots." Masked edits add a mask_image_url that constrains the change to a specific region, leaving everything outside the mask untouched. Reference-driven edits use one or more input images to preserve a subject or character's identity while generating a new scene around it.

Muapi exposes 70+ image-editing models — FLUX Kontext, Nano Banana, Qwen Image Edit, GPT-4o, Ideogram, MiniMax, and more — through the same unified REST pattern: one API key, one request/poll flow, pay-per-generation pricing with no subscription.

Instruction Edits vs. Masked Edits vs. Reference Edits

Use an instruction edit (FLUX Kontext, Nano Banana Edit, Qwen Image Edit Plus, ByteDance SeedEdit) when the change is describable in a sentence and doesn't need pixel-precise boundaries — a style change, an added object, a background swap. Use a masked edit (GPT-4o Edit, AI Object Eraser) when the change must stay confined to an exact region — removing an object cleanly, replacing only a specific area without disturbing the rest of the composition. Use a reference edit (MiniMax Subject Reference, Ideogram Character, FLUX PuLID) when the goal is keeping a specific subject or character recognizable across a brand-new generated scene, rather than editing the original photo's pixels directly. Reframing (Ideogram v3 Reframe) is a fourth, narrower pattern — no prompt at all, just a target aspect ratio, outpainting the canvas without touching existing content.

Representative Models

Source Upload and Prompt Structure

• Upload or link the source image(s). Every model accepts a public URL; use POST /api/v1/upload_file if you don't already have one.
• Multi-image models expect an ordered list. On images_list-based models, order matters — the first image is typically treated as the primary subject/base, later images as references or elements to incorporate.
• Masks are binary region maps. A mask image marks the editable region (commonly white = edit, black = keep) — check each model's exact convention before submitting.
• Instructions should describe the change, not the whole scene. Since the source image already fixes the composition, an instruction like "change the jacket to red leather" performs better than re-describing the entire photo.
• Output resolution/aspect ratio is often independently controllable — some models take an explicit aspect_ratio or width/height pair rather than inheriting the source image's dimensions automatically.

How to Call an Image Editing Model

1. Host the source image(s). Upload via POST /api/v1/upload_file, or use any publicly reachable URL.
2. Submit the request. POST /api/v1/{model-slug} with image_url (or images_list) and a prompt, plus a mask_image_url if the model supports masked edits.
3. Poll for completion. Check GET /api/v1/predictions/{request_id}/result until status is completed, then download the edited image.

curl -X POST https://api.muapi.ai/api/v1/gpt4o-edit \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "mask_image_url": "https://example.com/mask.png",
    "prompt": "replace the masked region with a clear blue sky"
  }'

import requests

response = requests.post(
    "https://api.muapi.ai/api/v1/gpt4o-edit",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "image_url": "https://example.com/photo.jpg",
        "mask_image_url": "https://example.com/mask.png",
        "prompt": "replace the masked region with a clear blue sky",
    },
)
request_id = response.json()["request_id"]

result = requests.get(
    f"https://api.muapi.ai/api/v1/predictions/{request_id}/result",
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(result.json())

Frequently Asked Questions