Endpoint
Creates an edited or extended version of an existing image based on a prompt.
Request
Must be multipart/form-data
The AI provider to use (e.g., openai)
Your API key for the specified provider
The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency.
A text description of the desired edits. Maximum length is 1000 characters.
An additional image whose fully transparent areas indicate where the original image should be edited. Must be a PNG file, less than 4MB, and have the same dimensions as the original image.
The model to use for image editing. Currently only dall-e-2 is supported.
Number of edited images to generate (1-10)
size
string
default:"1024x1024"
Size of the generated images: 256x256, 512x512, or 1024x1024
Format of the response: url or b64_json
Unique identifier for the end-user
Response
Unix timestamp of when the edited image was created
Array of edited imagesURL of the edited image (when response_format is url)
Base64-encoded image data (when response_format is b64_json)
Examples
Basic Image Edit
curl http://localhost:8787/v1/images/edits \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-F image="@original.png" \
-F prompt="Add a party hat to the cat" \
-F n=1 \
-F size="1024x1024"
Response
{
"created": 1677652288,
"data": [
{
"url": "https://..."
}
]
}
Python SDK
from portkey_ai import Portkey
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.edit(
image=Path("original.png").read_bytes(),
prompt="Add a party hat to the cat",
n=1,
size="1024x1024"
)
image_url = response.data[0].url
print(f"Edited image URL: {image_url}")
JavaScript SDK
import Portkey from 'portkey-ai';
import fs from 'fs';
const client = new Portkey({
provider: 'openai',
Authorization: 'sk-...'
});
const response = await client.images.edit({
image: fs.createReadStream('original.png'),
prompt: 'Add a party hat to the cat',
n: 1,
size: '1024x1024'
});
const imageUrl = response.data[0].url;
console.log(`Edited image URL: ${imageUrl}`);
Using a Mask
curl http://localhost:8787/v1/images/edits \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-F image="@original.png" \
-F mask="@mask.png" \
-F prompt="A sunflower in a vase" \
-F n=2 \
-F size="1024x1024"
Python with Mask
from portkey_ai import Portkey
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.edit(
image=Path("original.png").read_bytes(),
mask=Path("mask.png").read_bytes(),
prompt="A sunflower in a vase",
n=2,
size="1024x1024"
)
for i, img in enumerate(response.data):
print(f"Image {i+1}: {img.url}")
Download Edited Image
from portkey_ai import Portkey
import requests
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.edit(
image=Path("original.png").read_bytes(),
prompt="Change the background to a beach scene",
n=1,
size="1024x1024"
)
# Download and save
image_url = response.data[0].url
image_data = requests.get(image_url).content
Path("edited_image.png").write_bytes(image_data)
print("Edited image saved!")
Base64 Response
from portkey_ai import Portkey
import base64
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.edit(
image=Path("original.png").read_bytes(),
prompt="Add magical sparkles around the object",
response_format="b64_json"
)
# Decode and save
image_data = base64.b64decode(response.data[0].b64_json)
Path("edited.png").write_bytes(image_data)
Generate Multiple Variations
from portkey_ai import Portkey
from pathlib import Path
import requests
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.edit(
image=Path("original.png").read_bytes(),
prompt="Change the color scheme to vibrant and colorful",
n=4,
size="1024x1024"
)
# Save all variations
for i, img_data in enumerate(response.data):
image_content = requests.get(img_data.url).content
Path(f"variation_{i+1}.png").write_bytes(image_content)
print(f"Saved variation {i+1}")
Creating Masks
Masks are PNG images where:
- Transparent pixels (alpha = 0) indicate areas to edit
- Opaque pixels (alpha = 255) indicate areas to keep unchanged
Creating a Mask in Python (PIL)
from PIL import Image
import numpy as np
# Load original image
img = Image.open("original.png").convert("RGBA")
width, height = img.size
# Create a new image with transparency
mask = Image.new("RGBA", (width, height), (255, 255, 255, 255))
# Make a circular area transparent (to be edited)
center_x, center_y = width // 2, height // 2
radius = 200
for x in range(width):
for y in range(height):
if (x - center_x)**2 + (y - center_y)**2 < radius**2:
mask.putpixel((x, y), (255, 255, 255, 0))
mask.save("mask.png")
Image Requirements
- Format: Must be PNG with RGBA support
- Size: Less than 4MB
- Dimensions: Must be square (same width and height)
- Supported Sizes: 256x256, 512x512, or 1024x1024
- Transparency: If no mask is provided, the image must have transparent areas
Tips for Better Edits
- Clear Prompts: Be specific about what you want to change
- Use Masks: For precise control over edit regions
- Quality Images: Start with high-quality, clear images
- Appropriate Size: Use larger sizes (1024x1024) for better detail
- Generate Multiple: Use
n > 1 to get variations
Common Use Cases
- Object Replacement: Replace objects in images
- Background Changes: Change backgrounds while keeping subjects
- Style Transfer: Apply different styles to image regions
- Inpainting: Fill in missing or unwanted parts of images
- Enhancement: Add details or elements to existing images