Edit image

Edit or compose images from stored files or public URLs.

← All Image Generation endpoints · Capability overview

POST/v1/image-generation/edit

https://api.vee3.io/v1/image-generation/edit

50 tokens

Edit or compose images from stored files or public URLs.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

image-generation.edit

Parameters6 fields

promptstringRequired

Text description of the image to generate or of the edit to apply.

max length 4000

imagesarrayRequired

Source images as stored file names from files.list_uploaded_files and/or public http or https image URLs. One image is an edit. Several images are composed into one scene. Upload files with files.upload_file first.

min 1, max 8

nintegerOptional

Number of images to generate (1 to 10). Each returned image costs 50 tokens.

Default: 1 · min 1, max 10

sizestringOptional

Optional output size as WIDTHxHEIGHT (for example 1024x1536) or auto. This sets aspect ratio, not exact pixel size. Omit for the default aspect ratio.

max length 32

output_format"webp" | "png" | "jpeg"Optional

Encoding of the returned image. webp is smaller; png is lossless.

Default: "webp"

file_namestringOptional

Optional account-relative storage path for the image. When n is greater than 1, an index is inserted before the extension (for example art/fox.webp becomes art/fox-1.webp and art/fox-2.webp). If omitted, the file is stored under image-generation/ with a generated name.

max length 255

Response19 fields

generation_idstring

Unique identifier, prefix igen_.

statusstring

Always "completed" for a successful generation.

promptstring

Echo of the requested prompt.

image_countinteger

Number of images returned and billed.

token_costinteger

Tokens charged for this request (50 times image_count).

output_formatenum

Encoding of the stored images (webp, png, or jpeg).

sizestring

Echo of the requested size when one was passed.

created_atstring

ISO 8601 timestamp.

imagesarrayitems

8 fields

Generated images stored in account file storage.

image_urlstring

Signed download URL from account file storage.

file_namestring

Account-relative path where the image was stored.

file_size_bytesinteger

Image file size in bytes.

retained_untilstring

ISO 8601 timestamp when account storage retention expires.

download_codestring

Short code to pass to the @vee3/cli `vee3-get-file` command.

download_idstring

Stable identifier for the reserved download.

expires_atstring

ISO 8601 timestamp when the download code can no longer be resolved (60 minutes after reserve).

commandstring

Suggested terminal command for downloading to a local path.

install_commandstring

One-time command to install the Vee3 CLI (`npm install -g @vee3/cli`). On networks that inspect HTTPS, install may require Node 22.15+ with NODE_OPTIONS=--use-system-ca.

troubleshootingstring

What to do if installation or downloading fails: re-read this tool's description via meta-tools.describe for setup and troubleshooting steps.

HTTP errors: unauthorized, validation_error, insufficient_tokens, payment_required, uploaded_file_name_in_use, image_generation_timeout, image_generation_blocked, uploaded_file_not_found, url_blocked, image_input_not_supported

Example request

Python

import requests

url = "https://api.vee3.io/v1/image-generation/edit"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "prompt": "add a small red wool hat on the fox's head, keep the snowy forest background",
    "images": ["art/fox.webp"]
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Edited image saved to account file storage with signed URL and download code.

stored_edited_image.json

{
  "generation_id": "igen_example02abcdef12",
  "status": "completed",
  "prompt": "add a small red wool hat on the fox's head, keep the snowy forest background",
  "image_count": 1,
  "token_cost": 50,
  "output_format": "webp",
  "created_at": "2026-09-05T12:00:00Z",
  "images": [
    {
      "image_url": "https://f000.backblazeb2.com/file/vee3-user-uploads/acct/image-generation/igen_example02abcdef12.webp?Authorization=...",
      "file_name": "image-generation/igen_example02abcdef12.webp",
      "file_size_bytes": 184320,
      "retained_until": "2026-09-07T12:00:00Z",
      "download_code": "nR8qL4w1",
      "download_id": "7ab0d216-bbf7-6f0b-a8d5-0fe0de867417",
      "expires_at": "2026-09-05T13:00:00Z",
      "command": "vee3-get-file nR8qL4w1 ./path/to/save"
    }
  ],
  "install_command": "npm install -g @vee3/cli",
  "troubleshooting": "If installation or downloading fails, call meta-tools.describe with tool_name 'image-generation.generate' or 'image-generation.edit' and follow its setup and troubleshooting notes."
}