← Back to documentation
# Image API · gpt-image-2 / grok-imagine
English translation. Model names, API fields and executable examples retain their original text, including prompts and comments.
Generation and editing use the OpenAI Images protocol `POST /v1/images/generations` and `POST /v1/images/edits`. Specify aspect ratios through the `size` field as `宽x高` pixel dimensions.
Base URLhttps://yyds.seqnode.com/v1 Model gpt-image-2 / grok-imagine / grok-imagine-image / grok-imagine-image-quality Authentication Authorization: Bearer \ Maximum size 4K (longest side 3840)
## 01 · Endpoints and protocols
| Capability | Creation endpoint | Format |
|----|----|----|
| Text to image | POST `/v1/images/generations` | application/json |
| Image editing | POST `/v1/images/edits` | multipart/form-data (recommended) or application/json |
**Shared authentication:**`Authorization: Bearer YOUR_API_KEY`. Replace YOUR_API_KEY with the key issued by the platform. Images in multipart examples are uploaded files.
## 02 · Model capability differences
| Capability | gpt-image-2 | grok-imagine / -image / -image-quality |
|----|----|----|
| Text to image | Supported | Supported |
| Image editing | Supported | Supported (editing model`grok-imagine-edit`） |
| Reference-image count | By group: #127 has a confirmed limit of 10; #75 proxy limit is 15; consult the group guide | One image |
| Size tiers | 1K / 2K / 4K by longest side | Uses the selected model's`size` rules |
| Advanced parameters`quality` / `style` / `background` | Supported | Subject to the selected model's capabilities |
### Model aliases
- `grok-imagine` is a directly usable compatibility alias; you may also specify `grok-imagine-image` or `grok-imagine-image-quality`.
- For image editing, use `grok-imagine-edit`.
## 03 · Setting aspect ratios with size
Set the aspect ratio with the standard OpenAI field `size` as `宽x高` pixels, giving a ratio of `宽:高`. The system generates according to `size` and bills the corresponding tier.
- Format: `宽x高`, for example `1536x1024`（3:2）、`1024x1024` (1:1). Supported separators: `x`, `X`, `×`.
- If `size` is omitted, the selected model's default ratio is used (usually 1:1).
### Longest-side tiers (gpt-image-2 only)
The site's proposed tiering uses the longest side `max(宽, 高)`. The three common official 1K sizes and custom dimensions with a longest side of at most 1536 all fall under 1K.
| Tier | Longest-side rule | Common ratios and dimensions |
|----|----|----|
| 1K | `max(宽, 高) ≤ 1536` | `1024x1024`, `1536x1024`, `1024x1536` |
| 2K / upscaling | `1536 < max(宽, 高) < 3840` | `2048x2048`, `2048x1152`, `1152x2048` |
| 4K / upscaling | `max(宽, 高) ≥ 3840` | `3840x2160`, `2160x3840` |
### Custom size constraints
- Width and height must be multiples of 16.
- Each side must be ≤ 3840.
- Aspect ratio must be ≤ 3:1.
- Total pixels: 655,360–8,294,400.
**Note:**`1024x1536` has a longest side of 1536 and falls under 1K; `2048x768` has a longest side of 2048 and falls under 2K. This proposed rule applies only to `gpt-image-2`; Grok image models continue using their own `size` rules. **Rule status:**`gpt-image-2` billing now uses this longest-side rule consistently: ≤1536 is 1K, 1537–3839 is 2K, and ≥3840 is 4K. Grok image models continue following their own rules.
## 04 · Common field rules
| Field | Required | Description |
|----|----|----|
| `model` | is the | `gpt-image-2`, `grok-imagine`, `grok-imagine-image`, `grok-imagine-image-quality` (for editing,`grok-imagine-edit`）。 |
| `prompt` | Required for text to image | Description of the image. Recommended for editing; some models allow an image without a prompt. |
| `size` | No | `宽x高` pixels; see “03 · Setting aspect ratios”. Defaults to the selected model's default ratio. |
| `n` | No | Number of generated images; default 1. |
| `quality` | No | auto / high / medium / low; default auto (supported by gpt-image-2). |
| `style` | No | auto / vivid / natural; default auto. |
| `background` | No | auto / transparent / opaque; default auto. |
| `output_format` | No | png / jpeg / webp; default png. |
| `response_format` | No | `b64_json` or`url`; omission defaults to Base64. |
| `image` / `images` | Required for image editing | Input images: uploaded files with multipart, or a data URL array in JSON. gpt-image-2 limits depend on the group; consult the group guide. |
## 05 · Text-to-image example (gpt-image-2)
```
curl -X POST "https://yyds.seqnode.com/v1/images/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗台上，午后阳光",
"size": "1536x1024",
"n": 1,
"quality": "high",
"output_format": "png",
"response_format": "b64_json"
}'
```
## 06 · Image-editing examples
Upload the input image and optional mask with multipart:
```
curl -X POST "https://yyds.seqnode.com/v1/images/edits" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=把背景换成海边日落" \
-F "image=@input.png" \
-F "size=1536x1024" \
-F "response_format=b64_json"
```
For multiple references, repeat the `image` field; gpt-image-2 limits depend on the group; consult the group guide.
## 07 · Grok image model examples
### 7.1 Text to image (grok-imagine)
```
curl -X POST "https://yyds.seqnode.com/v1/images/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine",
"prompt": "A red apple on a white background",
"size": "1024x1024",
"n": 1
}'
```
`grok-imagine` can be used directly for generation; alternatively specify `grok-imagine-image` or `grok-imagine-image-quality`.
### 7.2 Image editing (grok-imagine-edit)
```
curl -X POST "https://yyds.seqnode.com/v1/images/edits" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=grok-imagine-edit" \
-F "prompt=edit this private image" \
-F "image=@input.png"
```
## 08 · Response format
Responses use the OpenAI Images format, with images in the `data` array:
```
{
"created": 1700000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUg...",
"revised_prompt": "..."
}
]
}
```
- `response_format=b64_json` (default) returns `data[].b64_json`.
- `response_format=url` returns `data[].url`.
## 09 · Common error checks
For 400 / 403 responses, check first:
1. Whether you omitted `model`.
2. Whether the API key belongs to a group with image generation enabled.
3. `size` is valid: dimensions divisible by 16, each side ≤3840, aspect ratio ≤3:1, and 655,360–8,294,400 total pixels.
4. Whether the edit request is missing `image`, or exceeds the model's reference limit (group-specific for gpt-image-2).
5. Whether an edit was sent to `/v1/images/generations` (editing requires `/v1/images/edits`）。
6. `quality` / `style` / `background` uses a valid enum value.
### Recommended calling patterns
- For generation use `/v1/images/generations` + JSON; for editing use `/v1/images/edits` + multipart。
- For a precise ratio, explicitly send `size`; if the ratio does not matter, omit it and use the model default.
- For 4K gpt-image-2 output, use a `size` with a longest side of 3840, such as 3840x2160.
- Grok image models may use `grok-imagine` (for generation) and `grok-imagine-edit` (for editing), or the full model names in the table.
Last updated: 2026-08-20
Official reference: OpenAI Image generation · GPT Image 2 model documentation