# Configuring Aspect Ratio Constraints for Special Screens in GPT-Image2

> Control GPT-Image2 aspect ratios for mobile, tablet, and cinematic screens using template guidance or runtime JSON. Optimize your special screen image generation today.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-08-31

---

**GPT-Image2 locks aspect ratios through template guidance defined in [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json).

### Extending Existing Templates

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

```json
{
  "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:

```json
{
  "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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) (lines 65-66).

### JSON Payload Configuration

Include the `aspect_ratio` field within `quality_constraints`:

```json
{
  "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:

```bash
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:

```bash
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json), invoke it directly:

```bash
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:

```bash
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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.