# 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.

**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](https://thelastapi.dev/blog/image-generation-api-developers).

## 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](https://thelastapi.dev/docs/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:

```ts
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```ts
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](https://thelastapi.dev/blog/image-to-video-api-product-animation).

## 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](https://thelastapi.dev/docs/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`:

```ts
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:

```bash
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 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](https://thelastapi.dev/blog/one-api-image-video-voice-models) or explore the full [AI documentation](https://thelastapi.dev/docs/ai).

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`.

---

Published 2026-11-15 · https://thelastapi.dev/blog/ai-photo-editing-api-reference-image
