86 lines
2.9 KiB
Markdown
86 lines
2.9 KiB
Markdown
---
|
|
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.
|
|
|