thelastapi
Get started free

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.

On this page 9 sections

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:

Terminal
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. 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, 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:

TypeScript
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:

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

Terminal
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:

Terminal
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:

TypeScript
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:

Terminal
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:

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

Image model comparison and pricing

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

ModelUnderlying engineCharacter consistency supportPrice
vibiz/imageNano Banana 2Yes (image_url, image_urls)about $0.067 per image
vibiz/image-proNano Banana 2.1Yes (image_url, image_urls)about $0.034 per image
vibiz/image-textGPT-5.4 Image 2Yes (prompt-focused text rendering)about $0.04 per image
vibiz/videoLTX-2.5 FastYes (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.

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:

Terminal
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 and storage management on the Files docs.

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.