thelastapi
Get started free

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

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 modelUnderlying lab modelBest suited forPrice per image
vibiz/imageNano Banana 2 (Google)Fast image edits, character consistency~$0.067
vibiz/image-proNano Banana 2.1 (Google)Newest Google model, refined quality~$0.034
vibiz/image-textGPT-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:

TypeScript
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:

Terminal
vibiz image "make the background a clean office space" \
  --from-image "https://thelastapi.dev/f/Qm9x1234567890abcdef1234567890ab/me.jpg" \
  --model vibiz/image \
  -o edited-profile.png

Using plain HTTP curl

With raw HTTP requests, send your bearer token and supply image_url within the JSON body:

Terminal
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:

Terminal
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:

Terminal
vibiz media-models face

Run a specialized model by setting its full id in the model field and supplying its expected parameters inside model_input:

TypeScript
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:

JSON
{
  "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:

TypeScript
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:

Terminal
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 receive 429 rate_limited with details.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 StatusError CodeReasonResolution
400invalid_requestmodel_takes_no_photoSelect an editing model like vibiz/image
400invalid_requestunknown_modelVerify model id via vibiz media-models
400invalid_requestcall_too_expensiveReduce duration or quality settings in model_input
429rate_limitedproject_budgetRaise budget in dashboard or CLI
503model_unavailableLab model unreachableRetry 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`.