How to Achieve Character Consistency in Batch Image Generation with GPT-Image-2

To maintain character consistency across batch image generation with GPT-Image-2, you must anchor identical character descriptions, style tags, and scene templates in every prompt while isolating only the variable elements, because the stateless Ciyuan API processes each request independently without seed parameters.

The freestylefly/awesome-gpt-image-2 repository provides a structured framework for deterministic visual output through its style library and template system. Since the backend endpoint at https://ciyuan.today/v1/images/generations treats every request as stateless, consistency depends entirely on prompt engineering rather than session persistence or seed locking.

Understanding the Stateless Architecture

The consistency challenge stems from the API's design. In api/generate-image.js, the server receives a JSON payload containing prompt and caseId, then forwards only the prompt string to the Ciyuan endpoint. There is no mechanism to pass a random seed or reference previous generations. Consequently, the model interprets each request in isolation, making prompt content the sole determinant of visual continuity.

To achieve character consistency batch image generation, you must treat the prompt as a deterministic recipe. Any deviation in whitespace, adjectives, or tag order can produce divergent results, even when depicting the same character.

Leveraging the Style Library as a Consistency Framework

The repository solves this through data/style-library.json, a structured catalog that defines reusable templates, styles, scenes, and categories. These elements act as stable anchors that you can reference across multiple API calls.

Template Structure and IDs

Each entry in the style library contains a unique id that represents a specific composition recipe. For example, a template with id: "character-standing-portrait" defines:

• Anchor: The core visual layout and composition rules
• Styles: Recommended aesthetic keywords (e.g., realistic, soft lighting, high detail)
• Scenes: Contextual tags that establish environment and lighting
• Pitfalls: Common phrasing patterns that introduce unwanted variation (such as contrasting adjectives)

By specifying the same template ID in every batch request, you ensure the model applies identical compositional rules to each image generation.

Validating Library References

The scripts/generate-style-skill.mjs utility validates the style library and generates a human-readable reference at agents/skills/gpt-image-2-style-library/references/style-library.md. This markdown file serves as authoritative documentation for selecting the exact template, style, and scene combinations required for your character batch.

Constructing Deterministic Prompts for Batch Generation

Achieving character consistency requires constructing prompts where fixed character attributes remain absolutely identical while only specified variables change.

Anchoring the Character Description

Create a single, detailed character paragraph that remains unchanged across the entire batch. This block should include immutable physical traits:

Character: A young female wizard with silver hair, emerald eyes, wearing a sapphire-embroidered cloak.

According to the source code analysis, this exact string must be copied verbatim into every prompt. Altering even a single adjective or punctuation mark risks generating a visually distinct character.

Pinning Style and Scene Tags

Append the style keywords and scene descriptors recommended by your selected template. These tags must remain constant:

Style: realistic, soft lighting, high detail, 4k resolution.
Scene: ancient library, rows of dusty tomes, warm amber glow.

The guidance field in data/style-library.json specifies which combinations produce stable results, while the pitfalls field warns against patterns that trigger randomness.

Isolating Batch Variables

When generating a batch, introduce variation only through isolated object descriptions. For instance, when depicting the same wizard holding different items, change only the final clause:

• Prompt 1: "holding a crystal orb that glows faintly."
• Prompt 2: "gripping a polished wooden staff topped with a ruby."
• Prompt 3: "brandishing a silver dagger with runic inscriptions."

All preceding sections—template ID, character description, style tags, and scene context—must remain identical across the batch to guarantee that the character's face, pose, clothing, and environmental lighting remain constant.

Implementation Example

Below is a practical Node.js implementation that constructs and sends a batch of consistent prompts to the repository's internal API endpoint (/api/generate-image):

import fetch from 'node-fetch';

const baseUrl = 'http://localhost:3000/api/generate-image';
const caseId = 42;
const templateId = 'character-standing-portrait';

// Fixed parts copied from style-library reference
const fixedPrompt = `
[Template ID: ${templateId}]
Character: A young female wizard with silver hair, emerald eyes, wearing a sapphire-embroidered cloak.
Style: realistic, soft lighting, high detail, 4k resolution.
Scene: ancient library, rows of dusty tomes, warm amber glow.
`;

const objects = [
  'holding a crystal orb that glows faintly.',
  'gripping a polished wooden staff topped with a ruby.',
  'brandishing a silver dagger with runic inscriptions.'
];

async function generateBatch() {
  const results = [];

  for (const obj of objects) {
    const payload = {
      prompt: `${fixedPrompt}\n${obj}`,
      caseId
    };
    
    const res = await fetch(baseUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    
    const json = await res.json();
    if (!json.ok) throw new Error(`Generation failed: ${json.error}`);
    results.push(json.image);
  }

  return results;
}

generateBatch()
  .then(images => console.log('Batch images:', images))
  .catch(err => console.error(err));

This implementation illustrates three critical principles: the fixedPrompt block remains identical for every request, only the object description changes per iteration, and each request targets the same generate-image endpoint defined in api/generate-image.js.

Summary

• Stateful backend limitations: The Ciyuan API at https://ciyuan.today/v1/images/generations processes requests independently without seeds, making prompt identity the only consistency mechanism.
• Template anchoring: Reference stable template IDs from data/style-library.json to enforce consistent composition and style rules across batches.
• Immutable character blocks: Copy identical character descriptions, style tags, and scene context into every prompt; change only isolated variables.
• Library validation: Use scripts/generate-style-skill.mjs to generate the reference documentation needed to select appropriate templates and avoid documented pitfalls.
• Precise string matching: Even whitespace variations can alter output, so treat prompt construction as deterministic code rather than natural language.

Frequently Asked Questions

How does the API handle character memory across batch requests?

The API does not maintain character memory or session state. According to the implementation in api/generate-image.js, each request is forwarded independently to https://ciyuan.today/v1/images/generations with no persistence mechanism. Character consistency batch image generation must be enforced entirely through identical prompt construction for every request in the batch.

What causes character drift when using the same template ID?

Character drift typically occurs when the prompt text deviates between requests, even minimally. This includes altered punctuation, substituted synonyms, reordered style tags, or extra whitespace. The pitfalls field in data/style-library.json specifically identifies linguistic patterns—such as contradictory adjectives—that trigger the model's internal randomness and should be eliminated from prompts.

Can I use seeds or reference images to lock character appearance?

No. The current Ciyuan endpoint exposed by freestylefly/awesome-gpt-image-2 does not accept seed parameters or reference image URLs. The only supported method for achieving consistent character rendering is to provide the model with identical textual descriptions, style tags, and scene contexts in every generation call, as documented in docs/templates.md.

How do I select the correct template for character portraits?

Consult the generated reference at agents/skills/gpt-image-2-style-library/references/style-library.md produced by scripts/generate-style-skill.mjs. This file indexes all available templates with metadata including useWhen and guidance fields that specify which templates yield stable results for character portraiture versus other compositions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}