omniclaw-skills/skills/sub2api-gpt-image-2/SKILL.md

name, description

name	description
sub2api-gpt-image-2	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:

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:

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:

{
  "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.