# Consistent characters with an image API

> Generate consistent characters with an image API by passing reference image URLs alongside your prompt to preserve facial features and style across scenes.

**You generate consistent characters with an image API by passing an anchor image URL into subsequent generation requests as a visual reference.** thelastapi supports this through the `vibiz/image` and `vibiz/image-pro` models by accepting `image_url` or `image_urls` directly inside `POST /v1/ai/images/generations`. This lets the model lock onto your character's facial structure, hair, and clothing style while rendering them across completely different poses, outfits, and backgrounds.

When you create visual stories, avatars, games, or marketing campaigns, generating a single good-looking character is easy. The hard part is getting that exact same character to appear in ten different scenes without shifting facial features or art styles. This guide explains how to anchor a character portrait, pass reference images via the API, and maintain visual consistency across scenes.

## Why character consistency breaks in generative models

Generative text-to-image models build images from scratch based on statistical probabilities tied to text prompts. Even if you use an identical prompt like `"a young woman with short curly black hair and green eyes wearing a denim jacket"`, each run produces a completely different person. 

Adding seed parameters helps in some workflows, but changing a prompt to place the person in a new setting—such as `"sitting in a subway car"` versus `"hiking up a mountain"`—shifts the entire latent layout. The character's face, facial proportions, and age drift immediately.

To keep a character consistent across calls, you must provide a reference image directly to the model. By supplying a reference image URL, the model conditions its generation on both the text prompt and the visual features of the provided image.

## Step 1: Generate your base character portrait

Before you can place your character in multiple scenes, generate a clear, high-resolution anchor portrait. For consistent results, keep the framing centered, the lighting neutral, and the background simple.

You can run this from your terminal using the CLI or with HTTP requests:

```bash
vibiz image "A clean front-facing portrait of an athletic man in his late 20s with short brown hair, amber eyes, and a charcoal crewneck, neutral lighting, plain grey background" \
  -o character_base.png \
  --model vibiz/image
```

When you call image generation within a thelastapi project, every generated asset is automatically stored in your project's [Files](https://thelastapi.dev/docs/files). The API returns a permanent URL that you can immediately reuse in your code:

```json
{
  "created": 1741500000,
  "data": [
    {
      "url": "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/2026-03-30-athletic-man-portrait.png",
      "file_id": "file_01k1234567890abcdef",
      "file_url": "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/2026-03-30-athletic-man-portrait.png"
    }
  ]
}
```

Because these URLs are permanent and public, you can feed `file_url` directly into your next API calls as the visual reference.

## Step 2: Render the character in new poses and scenes

Once you have your anchor image URL, pass it into the `image_url` field while describing the new setting and action in your prompt. 

Both `vibiz/image` (Nano Banana 2) and `vibiz/image-pro` (Nano Banana 2.1) accept image references. In [an AI photo editing API that starts from your photo](https://thelastapi.dev/blog/ai-photo-editing-api-reference-image), this mechanism is used to modify photos. Here, you use the same parameter to preserve your character's likeness while altering the context.

### Using the OpenAI SDK

Configure the OpenAI client with your thelastapi credentials:

```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 generateCharacterScene() {
  const characterUrl = 'https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/2026-03-30-athletic-man-portrait.png';

  const response = await openai.images.generate({
    model: 'vibiz/image',
    prompt: 'The character from the image reading a menu inside a brightly lit coffee shop, medium shot, smiling',
    response_format: 'url',
    // thelastapi accepts image_url directly on images.generate
    image_url: characterUrl,
  } as never);

  console.log('Scene 1 image:', response.data[0].url);
}

generateCharacterScene();
```

### Using cURL

You can execute the same call directly using standard HTTP:

```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": "The character wearing a yellow raincoat walking through rainy city streets at dusk",
    "image_url": "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/2026-03-30-athletic-man-portrait.png",
    "response_format": "url"
  }'
```

The underlying model inspects the face, hair texture, and general identity from the link and redraws the character in the raincoat on the rainy street.

## Step 3: Combine multiple references with image_urls

Sometimes you need to combine your consistent character with a specific item or setting, such as putting a custom jacket on your character or placing them in a specific branded office.

The `image_urls` array accepts up to 8 public image links. You can pass your character portrait as the first image and a photo of an outfit or product as the second. For a deeper breakdown of this technique, see how to [combine a person and a product in one image with an API](https://thelastapi.dev/blog/combine-person-and-product-image-api).

```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": "The person from the first image wearing the jacket from the second image, standing in a sunny park",
    "image_urls": [
      "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/character.png",
      "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/leather-jacket.png"
    ],
    "response_format": "url"
  }'
```

If you specify a model that does not accept reference photos—like older text-only engines—the API returns an HTTP `400` error with `details.reason: "model_takes_no_photo"`, ensuring you never waste money on a call that ignores your reference images.

## Step 4: Use specialized face-swap models for exact likeness

While reference-based generation with `vibiz/image` retains strong likeness, extreme camera angles or stylized art prompts can occasionally introduce subtle variations.

When your workflow demands strict face preservation across pre-rendered scenes or stock photos, you can call dedicated face-swapping models by id. Search for available models using the CLI:

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

To run a face swap, call `POST /v1/ai/images/generations` with the model ID and pass `face_image_0` alongside `target_image` 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,
});

const swap = await openai.images.generate({
  model: 'easel-ai/advanced-face-swap',
  prompt: 'swap',
  model_input: {
    face_image_0: 'https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/character.png',
    target_image: 'https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/action-pose.png',
  },
} as never);
```

This applies your character's exact face onto the target body and scene without regenerating the surroundings.

## Step 5: Animate your character into video

Once you have generated consistent still images of your character across various scenes, you can bring them to life using video models. thelastapi provides `vibiz/video`, which runs LTX-2.5 Fast to produce six-second clips at 720p with sound.

You can turn any character still into a moving video clip via the CLI:

```bash
vibiz video "The man turns toward the camera, smiles, and drinks from his mug" \
  -o character_scene.mp4 \
  --from-image https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/character-cafe.png \
  --aspect 16:9
```

With the API, video jobs use asynchronous polling under `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": "video",
    "model": "vibiz/video",
    "input": {
      "prompt": "The man waves hello and smiles",
      "image_url": "https://thelastapi.dev/f/Qm9x11223344556677889900aabbccddeeff/character.png",
      "aspect_ratio": "16:9"
    }
  }'
```

To learn more about orchestrating audio, stills, and video under a single key, see our guide on [one API for image, video and voice AI models](https://thelastapi.dev/blog/one-api-image-video-voice-models).

## Image model comparison and pricing

When building a character generation pipeline, choose the model that fits your image resolution, rendering speed, and budget:

| Model | Underlying engine | Character consistency support | Price |
| --- | --- | --- | --- |
| `vibiz/image` | Nano Banana 2 | Yes (`image_url`, `image_urls`) | about $0.067 per image |
| `vibiz/image-pro` | Nano Banana 2.1 | Yes (`image_url`, `image_urls`) | about $0.034 per image |
| `vibiz/image-text` | GPT-5.4 Image 2 | Yes (prompt-focused text rendering) | about $0.04 per image |
| `vibiz/video` | LTX-2.5 Fast | Yes (`image_url` still animation) | $0.54 per 6s video |

All image generation calls support resolutions from 256 px to 2,048 px per side and up to 4 images per single request. Detailed specifications and rate limits are listed on the [AI docs page](https://thelastapi.dev/docs/ai).

If you are paying Google directly, you can add your own Gemini key using `GEMINI_API_KEY=... vibiz ai keys set google`. When configured, calls to `vibiz/image` and `vibiz/image-pro` run against your Google credentials at zero cost on thelastapi.

## Next steps

Start by initializing your project and testing your anchor character portrait:

```bash
vibiz init "Character Engine" --resources ai
vibiz dev
```

Inspect your generated images in the dashboard under **Files** or fetch your newest character links directly in code with `@vibiz/app`. For next steps, review the full API schema on the [AI docs](https://thelastapi.dev/docs/ai) and storage management on the [Files docs](https://thelastapi.dev/docs/files).

## Frequently asked questions

### Can I pass more than one reference image to ensure character consistency?

Yes. You can pass up to 8 image links in the `image_urls` array on `POST /v1/ai/images/generations` to provide multiple angles of your character or combine a person with specific clothing.

### Where are the generated character images hosted?

Every image created within a project is automatically stored in the project's Files with a permanent public link. You can reuse the returned `file_url` as the reference image for future API calls.

### What happens if I pass an image URL to a model that does not support reference photos?

If a model only accepts text prompts, the API rejects the request with an HTTP 400 error and `details.reason: "model_takes_no_photo"` rather than silently ignoring your image.

### Can I animate my consistent character images into short video clips?

Yes. You can pass your character image link into `vibiz/video` via `POST /v1/ai/jobs` or the CLI flag `--from-image` to generate a 6-second animated video clip at 720p.

---

Published 2026-11-15 · https://thelastapi.dev/blog/consistent-characters-image-api
