# Face swap, upscaling and background removal by model id

> Run face swap, upscaling, and background removal models by model id through one OpenAI-compatible endpoint with permanent image hosting built in.

**You can run face swap, upscaling, and background removal models directly by model id using the thelastapi media endpoint, passing model-specific inputs alongside standard requests.** thelastapi gives you one API key to call specialized image models, track per-call costs, and automatically store output images in your project's permanent file storage.

Building visual features often forces developers to stitch together multiple niche providers, each with separate billing, separate authentication, and temporary output URLs that disappear after an hour. thelastapi unifies this process. You can query models like `easel-ai/advanced-face-swap`, background removal tools, or upscalers via a single gateway.

## Finding available image manipulation models

thelastapi exposes specialized media models beyond standard text-to-image prompts. You can search the catalog from your terminal using the CLI:

```bash
vibiz media-models "face swap"
vibiz media-models "upscaler"
```

You can also list and filter media models programmatically using the HTTP API:

```bash
curl https://thelastapi.dev/v1/ai/media-models?q=face%20swap \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

In Node.js applications with the SDK, call `vibiz.ai.mediaModels({ q: 'face swap' })`. The response returns each model id, its operational capability, and its live price unit (such as per image or per megapixel).

## How to call a face swap model

To run a face swap, call the `POST /v1/ai/images/generations` endpoint with your selected model id. Model-specific parameters—such as the source face image and the destination target image—are passed inside the `model_input` object (up to 16 KB).

Here is an example using the OpenAI TypeScript SDK pointed at thelastapi gateway:

```ts
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: process.env.VIBIZ_AI_BASE_URL,
  apiKey: process.env.VIBIZ_AI_API_KEY,
});

const response = await openai.images.generate({
  model: 'easel-ai/advanced-face-swap',
  prompt: 'swap',
  model_input: {
    face_image_0: 'https://thelastapi.dev/f/Qm9x.../source-face.png',
    target_image: 'https://thelastapi.dev/f/Qm9x.../target-body.png',
  },
} as never);

console.log('Result URL:', response.data[0].url);
```

You can execute the same operation via raw HTTP using `curl`:

```bash
curl https://thelastapi.dev/v1/ai/images/generations \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "easel-ai/advanced-face-swap",
    "prompt": "swap",
    "model_input": {
      "face_image_0": "https://thelastapi.dev/f/Qm9x.../source-face.png",
      "target_image": "https://thelastapi.dev/f/Qm9x.../target-body.png"
    }
  }'
```

Every response returns the generated image URL along with metadata confirming the exact model run (`served_model`) and the cost of the operation in micro-USD (`cost_micro_usd`).

## Running upscaling and background removal

Upscaling and background removal follow the identical invocation pattern. Locate the model id using `vibiz media-models` and provide the input image URL inside the `model_input` payload.

For longer renders, heavy processing tasks, or multi-frame video edits, submit the request as an asynchronous task via `POST /v1/ai/jobs`:

```bash
curl https://thelastapi.dev/v1/ai/jobs \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "clarity-upscaler",
    "input": {
      "prompt": "upscale",
      "model_input": {
        "image_url": "https://thelastapi.dev/f/Qm9x.../lowres.png"
      }
    }
  }'
```

When calling `POST /v1/ai/jobs`, the gateway answers immediately with HTTP `202 Accepted` and a job ID. You can poll `GET /v1/ai/jobs/:id` until execution completes. For broader visual workflows, 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).

## Editing photos with standard thelastapi models

If you do not need an explicit model id for face swapping or background isolation, you can perform image transformations using native thelastapi models like `vibiz/image` (Nano Banana 2), `vibiz/image-pro` (Nano Banana 2.1), or `vibiz/image-text` (GPT-5.4 Image 2).

These models accept an `image_url` or up to 8 `image_urls` directly to blend or alter visuals:

```bash
# Edit an image from the terminal
vibiz image "make the background a sunny beach" -o beach.png --from-image https://thelastapi.dev/f/Qm9x.../portrait.png
```

Or programmatically in TypeScript:

```ts
const edit = await openai.images.generate({
  model: 'vibiz/image',
  prompt: 'remove the background clutter and replace it with a clean studio wall',
  image_url: 'https://thelastapi.dev/f/Qm9x.../product.png',
} as never);

console.log('Edited image:', edit.data[0].url);
```

If you send an `image_url` to a model that only generates imagery from scratch from text, the gateway rejects the request with an HTTP `400` status and `details.reason: "model_takes_no_photo"`, ensuring you never waste credits on a mismatched call.

## Permanent asset storage with Files

A recurring issue when working with AI media APIs is handling output assets before the provider deletes them. With thelastapi, you do not need an external bucket or custom ingestion script.

Every image generated or edited using a project key is automatically stored in your project's [Files](https://thelastapi.dev/docs/files).

- **Permanent links:** The response object includes a permanent link in `url` (and `file_url`).
- **Identifier:** Each generated item receives a persistent `file_id`.
- **Searchable:** AI-generated files are named automatically by date and prompt (such as `2026-10-28-swap.png`).

You can inspect your media assets directly via the CLI:

```bash
# List all files generated by AI
vibiz files --source ai

# Retrieve only the link of your latest generated image
vibiz files latest --type image

# Search for specific outputs
vibiz files search "studio wall"
```

If a call is executed with an account key that lacks a project scope, the output file cannot be saved to persistent project storage. In that case, the resulting URL expires after 24 hours.

## Limits, pricing, and error handling

Calls against the [AI](https://thelastapi.dev/docs/ai) endpoints operate under deterministic boundaries to protect production environments:

| Metric | Account Key | Project Key |
| --- | --- | --- |
| Request rate | 300 req/min | 120 req/min (up to 600) |
| Token rate | 400k tokens/min | 200k tokens/min (up to 2M) |
| Concurrent calls | 50 in flight | 25 in flight (up to 50) |
| Default spend limit | $5/day | $1/day |
| Single-call ceiling | $10 max (`call_too_expensive`) | $10 max (`call_too_expensive`) |

When writing production code, structure your handlers around the standard OpenAI error format:

- `invalid_request` (HTTP 400): Model id is unknown or the payload exceeds constraints.
- `rate_limited` (HTTP 429): You exceeded concurrency, requests per minute, or your daily project/account budget. Inspect `details.reason` to see whether the trigger was `project_budget`, `daily_spend`, or throughput limits.
- `model_unavailable` (HTTP 503): The upstream model provider is temporarily down. thelastapi never silently switches your model to another lab's engine.

If you generate animated content or lip syncs, learn more in our guides on [calling Kling, Seedance and Veo by model id through one API](https://thelastapi.dev/blog/kling-seedance-veo-one-api) and [one API for image, video and voice AI models](https://thelastapi.dev/blog/one-api-image-video-voice-models).

To get started, create a project with `vibiz init "My Media App" --resources ai`, grab your key from `.env.development.local`, and run your first model call.

## Frequently asked questions

### Where are my processed images stored after a face swap or upscaling call?

Images generated using a project key are automatically saved to your project's Files drive with a permanent URL. If you run a request with an account-level key without specifying a project, the media URL remains valid for 24 hours.

### How does thelastapi handle model outages during image generation?

thelastapi never silently routes requests to an alternate model. If the requested model id is unavailable, the API returns an HTTP 503 `model_unavailable` error with a `details.retry_after_seconds` hint.

### Can I supply more than one reference image for image editing workflows?

Yes, endpoints supporting image edits with models like `vibiz/image` accept an `image_url` field or an `image_urls` array containing up to 8 public HTTPS image links.

### What is the maximum cost permitted for a single media model invocation?

Single calls to media models are hard-capped at $10. Any operation calculated above that threshold is rejected immediately with a `call_too_expensive` error code.

---

Published 2026-11-15 · https://thelastapi.dev/blog/face-swap-upscale-api-by-model-id
