OpenAI Image Edit API: a practical guide to safe image workflows

What the Image Edit API does

The name is slightly narrower than the capability. OpenAI's Image API has a generation endpoint for a new image from a prompt and an edits endpoint for changing an existing image with a new prompt. The edits endpoint can also create a new visual using other images as references.

For a one-off edit, use the Image API. For a conversational product where a person repeatedly refines a visual, OpenAI recommends the Responses API because it supports multi-turn editing and can accept image file IDs in context. Those are different interface choices, not a guarantee that one will produce a better business result.

An image edit is output, not confirmation that the underlying support problem is solved.

How to make an image edit useful

Start with the smallest specific job. A support team might want to add a clear marker to a customer-provided photo before handing a warranty claim to a specialist. A product team might need a revised product image for a help article. In both cases, decide the allowed source images and destination before writing a prompt.

The edit request includes an image and a prompt. It can also include a mask. A mask indicates the part of the first input image that should change, but OpenAI says GPT Image masking is prompt-based guidance and may not follow the mask's shape exactly. Treat it as an edit aid, not a pixel-accurate permission boundary.

The current guide also exposes size, quality, output format, compression, and background options. These settings affect the asset you receive, not whether the edit is factually appropriate. For example, a polished annotation can still mark the wrong component, hide evidence a claims reviewer needs, or create an image a customer should not receive.

Before connecting an edit to a live workflow, use a small evaluation set that includes:

• A clear input where the expected change is known.
• A photo with several similar objects, to see whether the right one is changed.
• A low-quality or incomplete image, where the correct outcome is a request for more evidence or a human handoff.
• A case involving a restricted or personal image, where the workflow must not send the file to an unapproved destination.
• A case where the customer-facing message and the back-office action must stay separate.

Review the output itself, then verify the next system separately. If an agent attaches an edited image to a ticket, check the ticket attachment and its visibility. If a workflow requests a replacement, confirm the order system's result before telling the customer it happened.

Model choice, cost, and safety

Do not design around a stale gpt-image-1 or DALL·E comparison table. The current OpenAI model catalog identifies gpt-image-2 as the default image model, while earlier GPT Image models are listed as previous or deprecated. Check the current model page and pricing when you choose a model.

For GPT Image 2, estimate all three parts of the request: prompt tokens, input-image tokens for edit requests, and image-output tokens. Image inputs are processed at high fidelity, so edit requests with reference images can carry more input cost. Higher output quality or larger output also changes cost and latency. Measure this against representative inputs rather than guessing from one square sample.

OpenAI may require organization verification before an account can use GPT Image models. The API can also block an input or output through its safety checks. A blocked request is not a reason to automatically retry unchanged. Record the request ID and error details, then revise the prompt or input only when the use case is appropriate and authorized.

For support work, include a separate privacy and policy check. A customer's photo can contain personal information, an address, a face, or information that should stay with a restricted team. Decide which team may view it, which service is approved to process it, how long it is kept, and who may send the resulting asset to a customer. The image model does not make those decisions.

Where eesel CLI fits in an image-based support workflow

The OpenAI Image Edit API is for building an image-editing capability. eesel is a ready-to-work teammate for defined jobs such as helpdesk work. eesel CLI is not an OpenAI image API and does not edit an image for you. It operates the same teammate and workspace available in the eesel dashboard.

That matters when a support lead wants to make a visual-support workflow safer before enabling it. The lead can work in the dashboard while an engineer, CI script, Claude Code, Codex, or Cursor reads JSON from the CLI. A concrete question might be: “Does the selected warranty teammate have the approved instruction for annotated photos, and does it hand off unclear damage rather than promise a replacement?” The coding agent can inspect and report; it should not silently connect an image service, alter permissions, or enable automation.

With Node.js 18.17 or newer, first confirm the signed-in workspace and identify the intended teammate:

npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents

TARGET_EESEL_AGENT="paste-agent-id-or-name-here"
npx @eesel/cli status --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli integrations --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli instructions --agent "$TARGET_EESEL_AGENT"

Those inspection commands can show what is connected, whether content has downloaded, and which standing rules apply. They do not prove that a live image action is safe or that a reply will be correct. Ask a coding agent for a read-only report first: list the warranty knowledge available, flag missing handoff language, and identify any configured connection that would receive customer images.

After the support owner approves a specific instruction or approved reference file, use --dry-run on the relevant write command before making it. Scope every command with --agent instead of relying on a saved default. Before a test chat, review the selected teammate's configured actions and permissions. Disable or contain actions outside the test scope; held approvals are not a substitute for knowing what can run without a hold.

Then test a fictional case in a new conversation. The purpose is to check the teammate's policy and handoff, not to claim that the terminal created an OpenAI image edit:

npx @eesel/cli new --name "warranty-photo-review" --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli chat "A customer sends an unclear photo of a damaged product. Explain what evidence is needed, do not promise a replacement, and state when a human reviewer must decide." --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli approvals --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli activity --agent "$TARGET_EESEL_AGENT"

Review the reply for its evidence request, policy boundary, and handoff. If the teammate created a held action, inspect it before a human approves it. After a controlled rollout, check the ticket, attachment access, and any order or warranty-system result. A downloaded source, JSON reply, held approval, or activity record by itself does not prove the customer received the right outcome.

The CLI's dashboard-management commands are free; chat is billed work. Its JSON output lets a script or coding agent produce an inspectable report, but it does not replace approval, representative testing, privacy review, or an external outcome check.

Choose the component that owns the job

Use the OpenAI Image Edit API when you need to build and operate a visual-editing capability. Plan for authorized image inputs, prompt and output review, error handling, costs, storage, and the systems that consume the result.

Use eesel when the job is operating a helpdesk teammate with your approved knowledge and workflows. Its CLI gives technical users a repeatable way to inspect and test the same teammate their support owners manage in the dashboard. For image-based support, keep the boundary clear: the image API creates an asset; the support workflow still needs a policy decision and a verified result.

Test image-based support with eesel

Try eesel if you want to operate a helpdesk teammate while keeping image-based cases inside an approved support workflow. Start with a small set of authorized, representative cases. Inspect sources and instructions, contain actions outside the test, test the required handoff, and verify the ticket and downstream outcome before widening customer access. Check eesel pricing separately from OpenAI image costs because they charge for different work.

The eesel Activity view shows a list of teammate activity with approved, rejected, and pending filters.