# Combine a person and a product in one image with an API

> Combine a person and a product using the AI image API by passing both photo URLs to POST /v1/ai/images/generations with image_urls and an edit prompt.

**You can combine a person and a product in one image by sending both photo URLs to `POST /v1/ai/images/generations` using the `image_urls` parameter.** thelastapi provides an OpenAI-compatible gateway where reference-capable models like `vibiz/image` and `vibiz/image-pro` accept up to 8 image links alongside your text instructions. Every render generated under a project key is automatically saved to your project's Files drive with a permanent URL.

This guide walks through structuring your multi-image requests, configuring reference-based edits, running specialized try-on models by id, and managing your assets.

## Why use reference images instead of text-only generation

Generating commercial product photos purely from text descriptions creates variations rather than accurate representations. If you ask an image model to render "a person wearing a navy linen button-down shirt," the model draws an imagined face, an imagined garment, and an imagined cut.

Using multiple reference images solves three concrete problems for eCommerce and catalog applications:

- **Garment accuracy.** Passing an existing product shot allows the model to preserve patterns, textures, collars, and logos rather than hallucinating details from words alone.
- **Subject consistency.** Supplying a reference photo of the subject ensures that facial features, pose, skin tones, and hair remain recognizable across different outfits.
- **Fail-safe parameter validation.** Some generative image models can only draw from text prompts. If you pass reference photos to a model that does not support image editing, the API immediately returns HTTP status `400` with `details.reason: "model_takes_no_photo"` rather than ignoring your images and billing you for an unrelated render.

To see how single reference images work for general photo modification, read [an AI photo editing API that starts from your photo](https://thelastapi.dev/blog/ai-photo-editing-api-reference-image).

## How to send multiple reference photos to the image API

To blend a person and a product, host both images at accessible HTTPS URLs. If your assets are local, you can upload them directly to your project's Files drive before calling the generation endpoint.

The generation endpoint accepts either `image_url` for a single image or `image_urls` for an array of up to 8 links.

### Using cURL with the REST API

Send a `POST` request to `/v1/ai/images/generations` containing the `model`, your instructional `prompt`, and the array of URLs in `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": "Dress the person from the first image in the trench coat from the second image, preserving the person pose and lighting",
    "image_urls": [
      "https://thelastapi.dev/f/Qm9xPersonSample/customer.jpg",
      "https://thelastapi.dev/f/Qm9xProductSample/trench-coat.png"
    ],
    "response_format": "url"
  }'
```

Setting `response_format: "url"` returns a direct public link. When called with a project key, this link is permanent and does not expire.

### Using the OpenAI SDK in TypeScript

Because the AI gateway is OpenAI-compatible under `/v1/ai`, you can initialize the standard OpenAI SDK using `process.env.VIBIZ_AI_BASE_URL` and `process.env.VIBIZ_AI_API_KEY`. The SDK accepts extended fields such as `image_urls`:

```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 generateTryOn() {
  const response = await openai.images.generate({
    model: 'vibiz/image-pro',
    prompt: 'Fit the jacket in the second photo onto the person in the first photo, matching the perspective and shadows.',
    image_urls: [
      'https://thelastapi.dev/f/sampleKey1/customer-pose.png',
      'https://thelastapi.dev/f/sampleKey2/leather-jacket.png',
    ],
    response_format: 'url',
  } as never);

  const image = response.data[0];
  console.log('Permanent image URL:', image.url);
  console.log('Files record ID:', (image as { file_id?: string }).file_id);
}

generateTryOn();
```

If your application already imports `@vibiz/app`, you can pass your configuration directly to the client with `new OpenAI(vibiz.ai)` without referencing separate environment variable names.

## Running specialized try-on and face models by id

Beyond the standard tiers, you can run any supported media model directly by its catalog identifier. This gives you access to specialized pipelines such as clothing try-on, face swap, upscaling, and background removal.

You can query the catalog programmatically using `GET /v1/ai/media-models`:

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

In TypeScript applications, retrieve catalog entries with the SDK:

```ts
import { vibiz } from '@vibiz/app';

const models = await vibiz.ai.mediaModels({ q: 'face-swap' });
console.log(models);
```

When invoking a specialized model by its id, pass model-specific arguments inside `model_input` (up to 16 KB):

```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 response = await openai.images.generate({
    model: 'easel-ai/advanced-face-swap',
    prompt: 'swap',
    model_input: {
      face_image_0: 'https://thelastapi.dev/f/sample1/person.png',
      target_image: 'https://thelastapi.dev/f/sample2/catalog-model.png',
    },
  } as never);

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

runFaceSwap();
```

Calls to specialized media models are metered against your balance at their live catalog price. Individual calls are subject to a maximum cap of $10; if a single operation exceeds this price, the request returns a `call_too_expensive` error. To review all media types available on a single key, see [one API for image, video and voice AI models](https://thelastapi.dev/blog/one-api-image-video-voice-models).

## Managing reference assets and renders in Files

Every project includes a dedicated Files drive. When an AI image request runs under a project key, the resulting graphic is saved directly to Files with metadata tracking its prompt, model, dimensions, and cost.

You can upload source person and product photos using the CLI:

```bash
vibiz files upload person.jpg jacket.png --folder virtual-try-on
```

To upload programmatically within your app using `@vibiz/app`:

```ts
import { vibiz } from '@vibiz/app';
import { readFileSync } from 'fs';

const fileBuffer = readFileSync('./hoodie.png');
const uploaded = await vibiz.files.upload(fileBuffer, {
  name: 'black-hoodie.png',
  contentType: 'image/png',
  folder: 'catalog-items',
});

console.log('Public asset link:', uploaded.url);
```

Public file URLs follow the structure `https://thelastapi.dev/f/<32-char-random-key>/<filename>`. These addresses cannot be guessed or enumerated, and they never expire.

You can inspect the latest images created by your AI workflows directly from your terminal:

```bash
vibiz files latest --type image --source ai
```

Or search stored files by prompt keywords:

```bash
vibiz files search "trench coat"
```

Files are isolated between development and production environments. Calls made using development keys save outputs to development Files, while production keys write to production Files. More file management operations are detailed in the [Files docs](https://thelastapi.dev/docs/files).

## Model options and pricing comparison

Different image models offer distinct trade-offs between rendering speed, price, and instruction fidelity:

| thelastapi model | Underlying lab model | Best used for | Price |
| --- | --- | --- | --- |
| `vibiz/image` | Nano Banana 2 (Google) | Fast image-to-image composition, consistent characters | About $0.067 per image |
| `vibiz/image-pro` | Nano Banana 2.1 (Google) | High-fidelity cloth textures, fine fabric details | About $0.034 per image |
| `vibiz/image-text` | GPT-5.4 Image 2 (OpenAI) | Compositions containing logos, labels, or typography | About $0.04 per image |
| Catalog models by id | Specialized media engines | Dedicated pipelines (try-on, face replacement, upscaling) | Live catalog price |

Each JSON response includes `cost_micro_usd`, giving you the exact cost of each generation down to the microdollar.

If you already have a Google AI Studio account, you can attach your own credentials by running `vibiz ai keys set google` (or passing `GEMINI_API_KEY`). When configured, Google-backed models (`vibiz/image`, `vibiz/image-pro`) execute on your Google account at no charge on thelastapi, while non-Google models continue billing through your thelastapi balance.

## Limits and error handling

When running virtual try-on workflows in production, keep the following limits and error behaviors in mind:

- **Image limits.** Requests accept 1 to 4 generated images per call, with resolutions ranging from 256 px to 2,048 px per side. The `image_urls` array supports up to 8 reference links.
- **Rate limits.** Account keys permit 300 requests and 400,000 tokens per minute (50 concurrent requests). Project keys permit 120 requests and 200,000 tokens per minute (25 concurrent requests).
- **Daily budgets.** Accounts have an initial daily spending ceiling of $5 across all AI operations. Projects default to a $1 daily AI budget. An owner can inspect or adjust project budgets using `vibiz ai budget <dollars>` or through the console.
- **Rate limit errors.** Exceeding a spending ceiling or token limit returns HTTP status `429` with `error.code: "rate_limited"`. The specific cause is stated in `details.reason` (such as `project_budget` or `daily_spend`).
- **No silent model substitutions.** If an upstream model is experiencing an outage, the API returns HTTP `503` with `error.code: "model_unavailable"` or `"provider_unavailable"`. The gateway never substitutes an unrequested model in place of your selection.

If you want to turn successful try-on compositions into moving marketing assets, read [an image-to-video API to animate a product photo](https://thelastapi.dev/blog/image-to-video-api-product-animation). The complete parameter specification is available in the [AI docs](https://thelastapi.dev/docs/ai).

To start combining person and product photos in your application, initialize your project using `vibiz init my-app --resources ai`, retrieve your API key from `.env.development.local`, and send your image links to `/v1/ai/images/generations`.

## Frequently asked questions

### What image formats can I pass in image_urls?

The endpoint accepts public HTTPS URLs pointing to PNG, JPEG, GIF, WebP, AVIF, and HEIC files. Uploaded files must be 50 MB or smaller.

### How many reference photos can I send in a single call?

You can include up to 8 reference URLs in the `image_urls` array on `POST /v1/ai/images/generations`. If you only have one reference image, you can use the single `image_url` property instead.

### Are generated try-on images kept permanently?

When an image is generated using a project key, it is automatically saved to your project's Files drive with a permanent URL that does not expire. Calls made without a project association return links that expire after 24 hours.

### What happens if I pass reference images to a model that only supports text?

The API returns HTTP status 400 with `details.reason: "model_takes_no_photo"`. It will never silently discard your reference images or generate an unguided image.

---

Published 2026-11-15 · https://thelastapi.dev/blog/combine-person-and-product-image-api
