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.
On this page 7 sections
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
400withdetails.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.
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:
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:
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:
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:
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):
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.
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:
vibiz files upload person.jpg jacket.png --folder virtual-try-onTo upload programmatically within your app using @vibiz/app:
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:
vibiz files latest --type image --source aiOr search stored files by prompt keywords:
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.
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_urlsarray 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
429witherror.code: "rate_limited". The specific cause is stated indetails.reason(such asproject_budgetordaily_spend). - No silent model substitutions. If an upstream model is experiencing an outage, the API returns HTTP
503witherror.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. The complete parameter specification is available in the AI docs.
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.