GPT Image 2 Image Generation Beta

## All APIs require Bearer Token authentication ## **Get API Key:** Visit [API Key Management Page](https://starmagic.ai/app/api-keys) to get your API Key **Add to request header:** ``` Authorization: Bearer YOUR_API_KEY ```

Authorization: Bearer YOUR_API_KEY

Image generation model name

"gpt-image-2-beta"

Prompt describing the image you want to generate, or describing how to edit the input image. Limited to 2000 tokens

"A beautiful colorful sunset over the ocean"

Aspect ratio of the generated image. Choose one of the supported ratios, or use `auto` to let the model decide: - `auto`: Determined automatically by the model (default), billed at the 1K tier - `1:1`: Square - `3:2` / `2:3`: Landscape / Portrait - `4:3` / `3:4`: Landscape / Portrait - `5:4` / `4:5`: Common social media - `16:9` / `9:16`: Widescreen landscape / portrait - `21:9` / `9:21`: Ultra-wide landscape / portrait - `2:1` / `1:2`: Landscape / Portrait - `3:1` / `1:3`: Panorama landscape / portrait **Explicit pixels `WxH`** are also supported (e.g. `1024x1024` / `1920x1080` / `3840x2160`). When using explicit pixels, the `resolution` field is ignored, and the billing tier is auto-bucketed by total pixels: - Total pixels ≤ 1.7 MP → 1K - Total pixels > 1.7 MP and ≤ 4.4 MP → 2K - Total pixels > 4.4 MP → 4K **Hard pixel limits:** - Both width and height must be multiples of `16` - Total pixels: `655,360` (≈ 0.65 MP) ~ `8,294,400` (≈ 8.29 MP) - Each side ≤ `3840` - Aspect ratio ≤ `3:1`

"16:9"

Resolution tier, only effective when `size` is a ratio. **When ignored:** - `size=auto`: billed at the 1K tier (no need to pass this parameter) - `size` is explicit `WxH` pixels: this field is ignored, and the tier is auto-bucketed by total pixels (see `size` description) **Pricing multiplier:** - `1K`: 1× base (default) - `2K`: 1.7× base - `4K`: 2.6× base **Landscape / square output dimensions** (portrait dimensions are the landscape width/height swapped): | Ratio | 1K | 2K | 4K | |---|---|---|---| | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `2:1` | 1456×720 | 2896×1456 | 3840×1920 \* | | `3:1` | 1776×592 | 3552×1184 | 3840×1280 \* | | `3:2` | 1248×832 | 2512×1680 | 3520×2352 | | `4:3` | 1184×880 | 2368×1776 | 3312×2480 \* | | `5:4` | 1152×912 | 2288×1824 | 3216×2576 | | `16:9` | 1360×768 | 2736×1536 | 3840×2160 (UHD) | | `21:9` | 1568×672 | 3136×1344 | 3840×1632 \* | \* Marks combinations that are auto-downscaled to fit the pixel budget.

"1K"

Reference image URL list for image-to-image and image editing features **Notes:** - Up to `16` reference images per request - Supported formats: `.jpeg`, `.jpg`, `.png`, `.webp` - Image URLs must be directly accessible by the server, or URLs that trigger direct download (typically URLs ending with image extensions like `.png`, `.jpg`)

[
  "https://example.com/image1.png",
  "https://example.com/image2.png"
]

HTTPS callback URL for task completion **Callback Timing:** - Triggered when task is completed, failed, or cancelled - Sent after billing confirmation **Security Restrictions:** - HTTPS protocol only - Internal IP addresses are prohibited (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.) - URL length must not exceed `2048` characters **Callback Mechanism:** - Timeout: `10` seconds - Maximum `3` retries after failure (at `1`/`2`/`4` seconds after failure) - Callback response format is consistent with task query API - 2xx status code is considered successful, other codes trigger retry

"https://your-domain.com/webhooks/image-task-completed"