An AI photo editing API that starts from your photo
Pass reference photos directly to image models via an OpenAI-compatible API to edit backgrounds, face features, or combine multiple images on one key.
On this page 7 sections
- Which models accept reference images and what do they cost?
- How do you edit a photo with a single reference image?
- How do you combine multiple reference images?
- How do you run specialized pipelines like face swaps?
- Where are edited images stored and how do you retrieve them?
- What limits, budgets, and error states apply?
- FAQ
The best API for AI image editing with reference images lets you pass an existing photo URL alongside an instruction prompt to modify the scene directly. Through thelastapi's OpenAI-compatible endpoint at POST /v1/ai/images/generations, you can pass a single image_url or up to eight image_urls to models like Nano Banana 2 (vibiz/image), Nano Banana 2.1 (vibiz/image-pro), and GPT-5.4 Image 2 (vibiz/image-text). You write a plain English prompt explaining what to change, and every generated output is automatically stored with a permanent link inside your project's Files drive.
This guide walks through configuring reference image requests, handling multi-image compositions, running specialized pipelines like face swaps, and managing your output files.
Which models accept reference images and what do they cost?
Not all image models support starting from an existing picture. If you pass an image reference to a model that only generates images from scratch, the gateway rejects the call immediately with an HTTP 400 invalid_request error and details.reason: "model_takes_no_photo". The API fails visibly instead of ignoring your reference and charging you for an unrelated result.
Three core models natively support reference-based image editing:
| thelastapi model | Underlying lab model | Best suited for | Price per image |
|---|---|---|---|
vibiz/image | Nano Banana 2 (Google) | Fast image edits, character consistency | ~$0.067 |
vibiz/image-pro | Nano Banana 2.1 (Google) | Newest Google model, refined quality | ~$0.034 |
vibiz/image-text | GPT-5.4 Image 2 (OpenAI) | Edits with readable text, long detailed prompts | ~$0.04 |
Beyond these default tiers, you can call specialized community pipelines by their explicit model id. Running vibiz media-models lists models for tasks such as face swapping, upscaling, and background removal, billed against your account balance at their live catalogue price. For pure prompt-to-canvas generation, check our guide on an image generation API for developers: Nano Banana and GPT Image on one key.
How do you edit a photo with a single reference image?
To edit a single image, send your modification prompt and a public HTTPS image URL to the image generations endpoint. The reference image can come from an external server or from an existing upload in your project's Files.
Using the OpenAI TypeScript SDK
Because thelastapi exposes an OpenAI-compatible interface under /v1/ai, you can configure the standard openai package using your environment variables:
import OpenAI from 'openai';
const openai = new OpenAI({
baseURL: process.env.VIBIZ_AI_BASE_URL,
apiKey: process.env.VIBIZ_AI_API_KEY,
});
async function editPhoto() {
const response = await openai.images.generate({
model: 'vibiz/image',
prompt: 'Change the background to a sunny Mediterranean beach, keeping the subject unchanged',
image_url: 'https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/portrait.png',
response_format: 'url',
} as never);
console.log('Edited image URL:', response.data[0].url);
console.log('Permanent File ID:', (response.data[0] as unknown as { file_id: string }).file_id);
}
editPhoto();Using the vibiz CLI
From your terminal or an automated script, the vibiz image command accepts the --from-image flag to perform edits:
vibiz image "make the background a clean office space" \
--from-image "https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/me.jpg" \
--model vibiz/image \
-o edited-profile.pngUsing plain HTTP curl
With raw HTTP requests, send your bearer token and supply image_url within the JSON body:
curl https://thelastapi.dev/v1/ai/images/generations \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "vibiz/image-pro",
"prompt": "Convert the lighting to warm golden hour",
"image_url": "https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/input.jpg",
"response_format": "url"
}'Every response returns the standard image payload along with two extended fields: file_id and file_url, giving you direct access to the persistent storage entry created for your project.
How do you combine multiple reference images?
Many workflows require combining elements from different sources, such as placing a model into an outfit or putting a product onto a new surface.
To combine sources, pass an image_urls array containing up to eight public HTTPS image URLs:
curl https://thelastapi.dev/v1/ai/images/generations \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "vibiz/image",
"prompt": "Place the product from the second photo onto the marble counter shown in the first photo",
"image_urls": [
"https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/kitchen.png",
"https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/bottle.png"
],
"response_format": "url"
}'When supplying multiple URLs, state clearly in your prompt how the inputs should be combined. Models like vibiz/image evaluate each reference in order to blend style, subjects, and lighting into a cohesive output.
How do you run specialized pipelines like face swaps?
General image editing models handle context and style modifications, but exact identity replacements or specific structural adjustments often need dedicated pipelines.
You can inspect all available visual models using the CLI:
vibiz media-models faceRun a specialized model by setting its full id in the model field and supplying its expected parameters inside model_input:
import OpenAI from 'openai';
const openai = new OpenAI({
baseURL: process.env.VIBIZ_AI_BASE_URL,
apiKey: process.env.VIBIZ_AI_API_KEY,
});
async function runFaceSwap() {
const result = await openai.images.generate({
model: 'easel-ai/advanced-face-swap',
prompt: 'swap',
model_input: {
face_image_0: 'https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/face.png',
target_image: 'https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/scene.png',
},
} as never);
console.log('Result URL:', result.data[0].url);
}
runFaceSwap();Individual calls using model_input are checked against a safety ceiling of $10 per request (call_too_expensive). If you want to animate your edited output into video clips, see our guide on an image-to-video API to animate a product photo.
Where are edited images stored and how do you retrieve them?
When an image request is linked to a project, the result is saved automatically to Files. You do not need an auxiliary upload step or an external storage bucket to keep your images from disappearing.
Every saved asset includes metadata describing how it was created:
{
"object": "file",
"id": "file_01k1234567890abcdef",
"environment": "production",
"name": "2026-10-28-beach-background.png",
"kind": "image",
"width": 1024,
"height": 1024,
"source": "ai",
"ai": {
"model": "vibiz/image",
"prompt": "Change the background to a sunny Mediterranean beach…",
"cost_usd": 0.067
},
"url": "https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/2026-10-28-beach-background.png",
"url_expires_at": null
}The resulting url contains a 32-character random key that cannot be guessed or enumerated, and it never expires. You can place this URL directly in an <img> tag or persist it in your database.
You can inspect your generated files programmatically with @vibiz/app:
import { vibiz } from '@vibiz/app';
// Find the newest AI-generated image in your project
const latest = await vibiz.files.latest({ type: 'image', source: 'ai' });
console.log('Latest edited image:', latest.url);Or query your assets directly with the CLI:
vibiz files latest --type image
vibiz files search "beach"Calls made with an account-level key without specifying a project do not write to project storage, and their generated URLs expire after 24 hours.
What limits, budgets, and error states apply?
When integrating photo editing into production features, keep these platform constraints in mind:
- Dimensions: Both source images and generated files must stay between 256 and 2,048 pixels per side.
- Batch size: Up to 4 images can be generated per request.
- File size: Uploads to Files accept up to 50 MB per file.
- Daily budgets: Projects have a default daily AI spend budget of $1 (customizable in project settings or via
PATCH /v1/projects/:id/ai). When reached, requests receive429 rate_limitedwithdetails.reason: "project_budget". - Account ceilings: Accounts have a default UTC daily spend limit of $5 across all AI operations.
Errors follow standard OpenAI formats:
| HTTP Status | Error Code | Reason | Resolution |
|---|---|---|---|
| 400 | invalid_request | model_takes_no_photo | Select an editing model like vibiz/image |
| 400 | invalid_request | unknown_model | Verify model id via vibiz media-models |
| 400 | invalid_request | call_too_expensive | Reduce duration or quality settings in model_input |
| 429 | rate_limited | project_budget | Raise budget in dashboard or CLI |
| 503 | model_unavailable | Lab model unreachable | Retry after the specified delay; models are never silently swapped |
To learn how to combine images with speech, transcriptions, and language models across your entire stack, read one API for image, video and voice AI models or explore the full AI documentation.
Create a new project with vibiz init "My Studio" --resources ai to begin editing photos using reference images today.
Frequently asked questions
Can I use local image files directly in the API call?
No, the API requires a public HTTPS URL passed in `image_url` or `image_urls`. You can upload local files up to 50 MB to your project storage first using `vibiz files upload <path>` or `POST /v1/projects/:id/files` to generate a permanent link.
What happens if an image model does not support reference images?
The API returns an HTTP 400 error with `details.reason: "model_takes_no_photo"`. It will never quietly drop your image references and generate an unprompted image from scratch.
How long do output image URLs remain accessible?
When an image is generated under a project, it is permanently saved in the project's Files drive and the URL never expires. Calls billed directly to an account key without a project link expire after 24 hours.
Can I run custom community models for tasks like upscaling or face swaps?
Yes, you can query available pipelines with `vibiz media-models` and invoke them by passing their model id to `POST /v1/ai/images/generations` with custom parameters placed in `model_input`.