AI Avatar Generation API — Consistent Character Images for Apps and Games
You're building a social app, RPG, or SaaS dashboard and need to generate profile avatars or character portraits on demand — without a human designer in the loop for every request. The challenge isn't just generating one good image; it's generating hundreds that look like they belong in the same visual universe, at a cost that holds up as your user count grows.
This guide covers how to call an AI image generation API to produce avatars at scale using Nano Banana Pro on GenRelay, including reference-guided consistency techniques, batch generation patterns, and prompt strategies that produce reliable results.
Why Does Avatar Generation Need a Dedicated API Strategy?
Standard text-to-image generation works for one-off images but breaks down at scale in three ways:
- Style drift — each prompt produces a stylistically independent image unless you anchor it to a reference.
- Throughput — generating 50 avatars synchronously will exceed typical timeout windows; you need a concurrent batch pattern.
- Cost predictability — per-image pricing means your COGS scale linearly with users, so you need exact numbers upfront before you commit to a pricing model for your product.
Nano Banana Pro's reference-guided generation mode addresses points 1 and 3 directly. GPT-image-2's instruction-based editing covers cases where you need to modify an existing avatar rather than generate one from scratch.
Which Model Should You Use for Avatar Generation?
| Requirement | Recommended model | Reason |
|---|---|---|
| Consistent style across many avatars | Nano Banana Pro | Reference image anchors style and palette |
| One-off portrait from a text prompt | Nano Banana Pro or GPT-image-2 | Both produce high-quality headshots |
| Edit an existing user-uploaded photo | GPT-image-2 | Instruction-based inpainting |
| 4K output for print or marketing use | Nano Banana Pro 4K | Highest resolution tier available |
| Budget-first at high volume | GPT-image-2 | Lower per-image cost at $0.014 |
As of September 2026, Nano Banana Pro is the recommended default for avatar generation pipelines that require visual consistency across a set of images. For details on portrait-specific prompt strategies, see AI portrait generation API.
How Do I Authenticate with the GenRelay API?
Every request to GenRelay requires a Bearer token in the Authorization header. Get your API key from the GenRelay console after signing up.
import os, requests
GENRELAY_API_KEY = os.environ["GENRELAY_API_KEY"] # Never hardcode
HEADERS = {
"Authorization": f"Bearer {GENRELAY_API_KEY}",
"Content-Type": "application/json"
}
Store the key as an environment variable — never commit it to source control. On the server side, use a secrets manager (AWS Secrets Manager, GCP Secret Manager, or equivalent).
How Do I Generate a Basic Avatar from a Text Prompt?
Here's a minimal working request that produces a single 1K portrait:
import os, requests
GENRELAY_API_KEY = os.environ["GENRELAY_API_KEY"]
def generate_avatar(prompt: str, resolution: str = "1024x1024") -> str:
"""Returns the URL of the generated avatar image."""
response = requests.post(
"https://genrelay.ai/v1/images/generations",
headers={
"Authorization": f"Bearer {GENRELAY_API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "nano-banana-pro",
"prompt": prompt,
"size": resolution,
"n": 1
}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
url = generate_avatar(
"Professional portrait of a young software engineer, "
"studio lighting, neutral gray background, photorealistic, "
"square crop, shoulder-length frame"
)
print(url)
Nano Banana Pro image generation is synchronous — the response returns immediately with the generated image URL. The URL is valid for 24 hours; download and transfer to your own storage if you need persistence.
What Prompt Structure Produces Reliable Avatars?
Prompts for avatar generation benefit from explicit composition and lighting instructions. Generic prompts ("a person") produce inconsistent framing and crops. Structure your prompts around five elements:
- Subject — age range, gender expression, or fictional archetype (e.g., "elven ranger character")
- Lighting — "studio lighting", "soft diffused light", "dramatic rim lighting"
- Background — "neutral gray background", "blurred city bokeh", "plain white"
- Composition — "square crop", "head and shoulders", "portrait orientation"
- Style — "photorealistic", "illustrated", "stylized digital art", "anime-inspired"
Example prompt for a game character avatar:
"Fantasy rogue character portrait, young adult, dark hooded cloak,
sharp confident expression, dramatic studio lighting, dark stone
background, illustrated digital art style, square crop,
shoulder-length frame"
Keeping this structure consistent across your avatar set produces more visually coherent results even before you add reference-guided generation.
How Do I Keep Avatars Visually Consistent Across a Set?
Pass a reference_image_url to anchor style across multiple generations. Nano Banana Pro uses the reference to match aesthetic, color palette, and art direction while keeping each generated character distinct:
import os, requests
GENRELAY_API_KEY = os.environ["GENRELAY_API_KEY"]
def generate_avatar_with_reference(
prompt: str,
reference_url: str,
resolution: str = "1024x1024"
) -> str:
response = requests.post(
"https://genrelay.ai/v1/images/generations",
headers={
"Authorization": f"Bearer {GENRELAY_API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "nano-banana-pro",
"prompt": prompt,
"size": resolution,
"n": 1,
"reference_image_url": reference_url
}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
# 1. Generate a "master style" avatar that defines your visual identity
MASTER_STYLE_URL = "https://your-cdn.com/master-avatar-style.png"
# 2. Reference it for all subsequent characters
characters = [
"RPG warrior character, male, heavy plate armor, stoic expression",
"RPG mage character, female, purple robes, wise expression",
"RPG rogue character, androgynous, dark leather, cunning smirk",
]
avatar_urls = [
generate_avatar_with_reference(char, MASTER_STYLE_URL)
for char in characters
]
print(f"Generated {len(avatar_urls)} consistent avatars")
The reference anchors the visual style without forcing the same face — each character retains its own identity while sharing the same art direction as the rest of your set.
How Do I Generate Avatars in Batch?
For pipelines that need to produce dozens of avatars at once, use concurrent requests rather than sequential calls. Nano Banana Pro responds synchronously, so concurrency is achieved at the HTTP level:
import asyncio, httpx, os
GENRELAY_API_KEY = os.environ["GENRELAY_API_KEY"]
MAX_CONCURRENT = 5 # Respect your plan's concurrency limit
async def generate_one(
client: httpx.AsyncClient,
prompt: str,
semaphore: asyncio.Semaphore,
reference_url: str | None = None
) -> dict:
payload = {
"model": "nano-banana-pro",
"prompt": prompt,
"size": "1024x1024",
"n": 1
}
if reference_url:
payload["reference_image_url"] = reference_url
async with semaphore:
r = await client.post(
"https://genrelay.ai/v1/images/generations",
headers={"Authorization": f"Bearer {GENRELAY_API_KEY}"},
json=payload
)
r.raise_for_status()
return {"prompt": prompt, "url": r.json()["data"][0]["url"]}
async def batch_avatars(prompts: list[str]) -> list[dict]:
sem = asyncio.Semaphore(MAX_CONCURRENT)
async with httpx.AsyncClient(timeout=60.0) as client:
return await asyncio.gather(
*[generate_one(client, p, sem) for p in prompts]
)
prompts = [f"Professional avatar, user archetype {i}" for i in range(20)]
results = asyncio.run(batch_avatars(prompts))
print(f"Generated {len(results)} avatars")
For more patterns including retry logic and cost tracking, see Batch image generation via API.
What Does Avatar Generation Cost?
Nano Banana Pro pricing on GenRelay (as of September 2026):
| Resolution | Price per image |
|---|---|
| 1K (1024×1024) | $0.030 |
| 2K (2048×2048) | $0.030 |
| 4K (4096×4096) | $0.042 |
GPT-image-2 pricing: $0.014 per image at standard resolution.
Example workload math:
| Scenario | Volume | Model | Monthly cost |
|---|---|---|---|
| Standard user avatar on sign-up | 5,000 new users | Nano Banana Pro 1K | $150 |
| High-res avatar for premium users | 500 premium users | Nano Banana Pro 4K | $21 |
| Budget avatar tier | 10,000 new users | GPT-image-2 | $140 |
| Game character set (3 per user) | 1,000 new users | Nano Banana Pro 1K | $90 |
At $0.030 per image, generating one avatar per new user stays under $300/month for up to 10,000 sign-ups. GenRelay's free credits cover your first batch of testing, and the $14/mo plan includes a monthly credit allocation before pay-as-you-go begins.
For GPT-image-2, the lower per-image price ($0.014) makes it attractive for high-volume scenarios where reference-guided consistency is less critical.
FAQ
Does Nano Banana Pro support transparent backgrounds for avatars?
Not natively via the standard text-to-image endpoint. Generate the avatar with a solid neutral background, then apply background removal programmatically using a tool like rembg or a downstream cutout API.
Can I generate avatars that resemble a specific real person?
GenRelay's upstream model providers enforce content policies that restrict generation of realistic likenesses of named individuals. Use fictional character descriptions or stylized/illustrated styles instead.
What resolution should I target for mobile app profile pictures?
1K (1024×1024) is sufficient for display up to 512px, including on most high-DPI mobile screens. Use 2K if you plan to crop to non-square aspect ratios or need crisp rendering at larger sizes. Pricing is the same for 1K and 2K on Nano Banana Pro.
How long is the generated image URL valid?
Generated image URLs are valid for 24 hours. Transfer images to your own object storage (S3, GCS, or similar) immediately if long-term persistence is required.
Can I use GPT-image-2 to update an existing avatar rather than generate a new one?
Yes — GPT-image-2 supports instruction-based editing. Pass the existing image URL and an instruction like "add a subtle glow effect to the background" to modify the image without regenerating from scratch. See the GPT-image-2 model page for editing endpoint details.