---
name: sub2api-gpt-image-2
description: Use when Codex or another agent needs to call, document, troubleshoot, or generate code for GPT Image 2 through sub2api/OpenAI-compatible image APIs, including /v1/images/generations, /v1/images/edits, Responses image_generation tools, 4K image settings, streaming partial images, base64 decoding, and production error handling.
---

# Sub2API GPT Image 2

## Workflow

1. Treat `gpt-image-2` as an image generation/editing model, not a Codex or agent main model.
2. Use `/v1/images/generations` for direct text-to-image and `/v1/images/edits` for reference-image or mask edits.
3. Use `/v1/responses` with a text/agent model such as `gpt-5.5` plus an `image_generation` tool when an agent should reason before generating images.
4. Never print, commit, or hard-code real API keys. Read credentials from `API_KEY` and `BASE_URL`.
5. For detailed parameter rules, read `references/api.md`.
6. For quick non-streaming generation tests, run `scripts/generate_image.py`.

## Defaults

Use these defaults unless the task says otherwise:

```text
BASE_URL=https://claude.omniclaw.store/v1
model=gpt-image-2
size=1024x1024
quality=medium
output_format=png
n=1
timeout=300 for 4K, 120 otherwise
```

Use `3840x2160` only when explicitly requested or when a final 4K asset is needed. For prompt iteration, generate smaller images first.

## Direct Generation

Run:

```bash
export API_KEY="sk-..."
export BASE_URL="https://claude.omniclaw.store/v1"
python3 ~/.codex/skills/sub2api-gpt-image-2/scripts/generate_image.py \
  --prompt "A premium product poster for an AI service" \
  --size 1536x1024 \
  --quality medium \
  --output image.png
```

Use `--dry-run` to inspect payloads without calling the API.

## Editing

Use multipart form requests with `image[]=@file.png`; add `mask=@mask.png` only for local masked edits. For `gpt-image-2`, omit `input_fidelity` because it always processes image inputs at high fidelity.

## Responses Tool Pattern

For agentic workflows:

```json
{
  "model": "gpt-5.5",
  "input": "Generate a clean product poster for an AI proxy service.",
  "tools": [
    {
      "type": "image_generation",
      "size": "1536x1024",
      "quality": "medium",
      "output_format": "png"
    }
  ]
}
```

Do not set the Responses `model` to `gpt-image-2`.

## Troubleshooting

- `401`: wrong or disabled sub2api key.
- `400`: invalid params such as unsupported transparent background or invalid size.
- `429`: upstream account usage limit; prefer plus/team/pro accounts.
- `502`: upstream did not return image output, network failed, or content was refused; inspect sub2api logs and simplify the prompt.
- Long latency: 4K/high can take minutes; use `jpeg`, `quality=low|medium`, or smaller sizes for drafts.

## Safety

Reject or rewrite sexualized young-looking subjects, minors, non-consensual sexual content, explicit nudity, and other disallowed content before calling the API.