Configuring Aspect Ratio Constraints for Special Screens in GPT-Image2

GPT-Image2 locks aspect ratios through template guidance defined in data/style-library.json or via the quality_constraints.aspect_ratio field in runtime JSON payloads, enabling precise control for mobile, tablet, and cinematic displays.

The freestylefly/awesome-gpt-image-2 repository implements a data-driven prompt library where configuring aspect ratio constraints for special screens relies on a centralized template system. This architecture merges static guidance from JSON configuration files with dynamic runtime parameters, ensuring consistent compositional control across diverse display formats.

Understanding the Style Library Architecture

The core configuration resides in data/style-library.json, which defines every template—including UI layouts, posters, and product shots—alongside their guidance and pitfalls arrays. According to the source code, each template's guidance explicitly instructs the model to lock specific proportions, such as the Poster Layout System template which specifies aspect ratio locks at lines 23-24.

The gpt-image-2-style-library agent skill (located in agents/skills/gpt-image-2-style-library/SKILL.md) parses this JSON at runtime, merging template defaults with user-provided values to generate the final prompt. This design ensures the library remains the single source of truth while allowing per-request flexibility for special screen sizes.

Method 1: Template-Level Configuration

For consistent, reusable constraints across projects, modify the static guidance within style-library.json.

Extending Existing Templates

Locate the target template's guidance array and add a specific aspect ratio instruction:

{
  "id": "poster-layout-system",
  "guidance": {
    "en": [
      "Lock aspect ratio to 9:16 for portrait mobile screens.",
      "Emphasize vertical hierarchy and thumb-zone placement."
    ]
  }
}

Changes take effect immediately upon the next skill execution without code redeployment.

Creating Custom Templates for Special Screens

For unique display types like 2.39:1 cinematic widescreen, append a new template object to the library:

{
  "id": "cinematic-widescreen",
  "anchor": "tpl-cinematic",
  "title": { "en": "Cinematic Widescreen", "zh": "电影宽屏" },
  "category": "Posters & Typography",
  "guidance": {
    "en": [
      "Lock aspect ratio to 2.39:1 for cinematic widescreen.",
      "Emphasize title hierarchy and dramatic lighting."
    ]
  }
}

Method 2: Runtime Configuration

When you need ad-hoc flexibility without modifying the library, supply constraints via the JSON payload or CLI flags as documented in docs/templates.md (lines 65-66).

JSON Payload Configuration

Include the aspect_ratio field within quality_constraints:

{
  "type": "Custom Generation",
  "objective": "Create a mobile-first poster",
  "inputs": {
    "subject": "New smartphone launch",
    "scene": "Clean studio background",
    "style": "Modern high-contrast",
    "palette": "Blue-white"
  },
  "quality_constraints": {
    "resolution": "4K",
    "aspect_ratio": "9:16",
    "composition": "Rule of thirds"
  },
  "output_requirements": {
    "usage": "App splash screen",
    "focus": "Device silhouette"
  }
}

The skill automatically merges this value into the generated prompt, overriding any template default.

CLI Flag Override

When using the command-line interface, pass the --ratio flag:

npx gpt-image-2-style-library generate \
  --template poster-layout-system \
  --subject "Spring sale" \
  --scene "Outdoor market" \
  --style "Vibrant" \
  --palette "warm" \
  --ratio 16:9

Explicit CLI values take precedence over both template defaults and JSON payload settings.

Practical Implementation Examples

Mobile Portrait Generation (9:16)

Generate mobile-optimized artwork using either the CLI flag or a custom template:

npx gpt-image-2-style-library generate \
  --template poster-layout-system \
  --subject "Fitness App Promo" \
  --ratio 9:16

Cinematic Widescreen Template (2.39:1)

After adding the cinematic template to style-library.json, invoke it directly:

npx gpt-image-2-style-library generate \
  --template cinematic-widescreen \
  --subject "Space epic"

This automatically applies the 2.39:1 constraint defined in the template's guidance.

Runtime Override of Template Defaults

Even templates with built-in ratios can be superseded at call-time:

npx gpt-image-2-style-library generate \
  --template cinematic-widescreen \
  --subject "Space epic" \
  --ratio 21:9

This command uses the cinematic template's styling guidance but replaces the default 2.39:1 ratio with 21:9.

Summary

• Template configuration happens in data/style-library.json, where the guidance array instructs the model to lock specific aspect ratios for reusable screen formats.
• Runtime overrides use the quality_constraints.aspect_ratio field in JSON payloads or the --ratio CLI flag for one-off generations.
• The gpt-image-2-style-library skill merges these values at runtime, ensuring the library remains authoritative while supporting ad-hoc flexibility.
• Changes to style-library.json take effect immediately without rebuilding, as the skill reads the file dynamically according to the source implementation.

Frequently Asked Questions

Where are aspect ratio constraints defined in GPT-Image2?

According to the source code in freestylefly/awesome-gpt-image-2, constraints are defined in two locations: the guidance arrays within data/style-library.json for template-level defaults, and the quality_constraints.aspect_ratio field in runtime JSON payloads. The agent skill located at agents/skills/gpt-image-2-style-library/SKILL.md processes both sources during prompt generation.

Can I override a template's default aspect ratio?

Yes. Supply an explicit aspect_ratio value in your JSON request body or use the --ratio CLI flag. As implemented in the repository, runtime values override template defaults, allowing you to use a poster template's styling logic while changing its proportions for mobile or ultra-wide displays.

What file should I edit to add permanent aspect ratio rules for new screen types?

Edit data/style-library.json to add new templates or modify existing guidance arrays. For example, adding "Lock aspect ratio to 21:9 for ultrawide monitors" to a template's guidance ensures every generation using that template respects those proportions. The skill reads this file dynamically, so no rebuild is required.

How do I structure a JSON payload for custom aspect ratios?

As documented in docs/templates.md at lines 65-66, include the ratio within the quality_constraints object. A valid payload sets "aspect_ratio": "9:16" alongside other constraints like resolution and composition, which the skill merges into the final prompt sent to the image generation model.

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