# GeiliAPI GPT Image 2 — LLM integration spec

Human docs: https://sub.geiliapi.com/docs/gpt-image.html
Web studio: https://sub.geiliapi.com/image-studio/  (engine: GPT Image)

Use this file to implement a client. Do not put `gpt-image-2` into Codex, Claude, Gemini, or Grok chat CLIs. GPT Image 2 generates images only, not video.

## Auth and groups

Create keys in https://sub.geiliapi.com  → API 密钥.

| Task | Key group | quality | Notes |
|---|---|---|---|
| 1K | GPT Image 2 - 1K | low | Standard key |
| 2K | GPT Image 2 - 2K4K | medium | HD key |
| 4K | GPT Image 2 - 2K4K | high | Same HD key |

Do not use OpenAI/Codex chat keys, Grok keys, or Grok（Heavy）keys. Do not mix 1K keys with 2K/4K requests.

Header: `Authorization: Bearer <KEY>`

## Base URLs

- Image generate/edit (long requests): `https://image-direct.geiliapi.com/v1`
- Models / key management: `https://sub.geiliapi.com/v1`
- Never send image jobs to `sub.geiliapi.com` (Cloudflare ~125s idle timeout → HTTP 524).
- `image-direct.geiliapi.com` bypasses Cloudflare, nginx timeout 600s.

Anonymous `POST https://image-direct.geiliapi.com/v1/images/generations` must return 401.

## Models

Default: `gpt-image-2`
Also accepted if the console lists them: `gpt-image-1.5`, `gpt-image-1`

## Text-to-image

`POST https://image-direct.geiliapi.com/v1/images/generations`
`Content-Type: application/json`

```json
{
  "model": "gpt-image-2",
  "prompt": "a cinematic product photo, clean studio, soft natural light, high detail",
  "quality": "low",
  "size": "1024x1024",
  "n": 1
}
```

`n` is 1–4. `quality` is required.

## Image-to-image

`POST https://image-direct.geiliapi.com/v1/images/edits`
`multipart/form-data`

Fields:
- `model=gpt-image-2`
- `prompt=...`
- `quality=low|medium|high`
- `size=<whitelist or auto>`
- `n=1`
- first file: `image`
- extra files: `image[1]`, `image[2]`, `image[3]`
- max 4 reference images

`size=auto` follows the reference image aspect ratio.

## Size whitelist

Upstream uses `quality` for tier and `size` for aspect. Only these values work.

1K / quality=low:
- 1024x1024 (1:1)
- 1536x1024 (3:2)
- 1024x1536 (2:3)

2K / quality=medium:
- 2048x2048 (1:1)
- 2048x1152 (16:9)
- 1152x2048 (9:16)

4K / quality=high:
- 2880x2880 (1:1)
- 3840x2160 (16:9 UHD)
- 2160x3840 (9:16 UHD)

Hard constraints: longest side ≤ 3840, pixels ≤ 8294400. Never send `4096x4096`. 1K landscape/portrait is 3:2 / 2:3, not 16:9.

## Response

OpenAI-compatible `data[]` items with `url` or `b64_json`.

After a paid success, console「使用记录」must show the 1K or 2K4K key and `gpt-image-2`.

## Errors

- 401 / wrong group: used a chat key or crossed 1K vs 2K4K
- invalid image size: size not in the whitelist (256x256 / 512x512 are not generatable; generate 1K and downscale client-side — the web studio has an "export size" 512/256 option that only affects downloads)
- 524: request hit `sub.geiliapi.com`
- safety/policy: rewrite prompt or reference image
- 413: compress or drop reference images

Pricing: https://sub.geiliapi.com/model-pricing/
Updated: 2026-08-25