> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypergate.store/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation

> POST /v1/images/generations and POST /v1/images/edits — generate or edit images synchronously.

## Endpoints

| Method | Endpoint | Type | Notes |
| - | - | - | - |
| `POST` | `/v1/images/generations` | Text to Image | Sync — returns URL immediately |
| `POST` | `/v1/images/edits` | Image to Image | Sync — returns URL immediately |
| `POST` | `/v1/images` | Legacy alias | Async 202 — same as generations; poll `GET /v1/images/{id}` |
| `GET` | `/v1/images/{id}` | Poll legacy job | For jobs created via `POST /v1/images` (legacy) |

<Note>
  Use `capabilities.endpoint` from `GET /v1/models` to know which endpoint to call:

  * `"/v1/images/generations"` → `POST /v1/images/generations` (text-to-image)
  * `"/v1/images/edits"` → `POST /v1/images/edits` (image-to-image)
</Note>

***

## POST /v1/images/generations

Synchronous text-to-image. Returns the image URL directly with **HTTP 200**.

### Request

<ParamField header="Authorization" type="string" required>
  `Bearer <your-token>`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

### Body

<ParamField body="model" type="string" required>
  Model ID. Accepted: `gpt-image-2`, `gpt-image-2/text-to-image`, `gpt-image-1`, `gpt-image-1/text-to-image`, `dall-e-3`, `dall-e-3/text-to-image`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare/text-to-image`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst/text-to-image`. If you omit the `/text-to-image` suffix it is added automatically.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the image to generate.
</ParamField>

<ParamField body="size" type="string">
  Output dimensions. Examples: `1024x1024`, `1536x1024`, `1024x1536`, `auto`. `gpt-image-2.5-flare`/`gpt-image-2.5-sunburst` also support resolutions up to `3840x2160`.
</ParamField>

<ParamField body="quality" type="string">
  Image quality. gpt-image-2/gpt-image-1: `low`, `medium`, `high`, `auto`. dall-e-3: `standard`, `hd`. `gpt-image-2.5-flare`/`gpt-image-2.5-sunburst`: `auto`, `low`, `medium`, `high`, plus `xhigh` and `max` (higher cost per image).
</ParamField>

<ParamField body="style" type="string">
  Image style for dall-e-3. Values: `vivid`, `natural`.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://hypergate.store/v1/images/generations \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "prompt": "A futuristic city at sunset, cinematic lighting",
    "size": "1536x1024",
    "quality": "high"
  }'
```

### Response `200`

```json theme={null}
{
  "created": 1720000000,
  "data": [
    { "url": "https://cdn.hypergate.store/outputs/abc123.png" }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 0, "total_tokens": 12 }
}
```

***

## POST /v1/images/edits

Synchronous image-to-image editing. Returns the result URL directly with **HTTP 200**.

### Request

<ParamField header="Authorization" type="string" required>
  `Bearer <your-token>`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

### Body

<ParamField body="model" type="string" required>
  Model ID. Accepted: `gpt-image-2`, `gpt-image-2/image-to-image`, `gpt-image-1`, `gpt-image-1/image-to-image`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare/image-to-image`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst/image-to-image`. If you omit the `/image-to-image` suffix it is added automatically.
</ParamField>

<ParamField body="prompt" type="string" required>
  Editing instruction or description.
</ParamField>

<ParamField body="image" type="string" required>
  Input image URL (publicly accessible).
</ParamField>

<ParamField body="size" type="string">
  Output dimensions. Examples: `1024x1024`, `1536x1024`, `1024x1536`, `auto`.
</ParamField>

<ParamField body="quality" type="string">
  Image quality: `low`, `medium`, `high`, `auto`.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://hypergate.store/v1/images/edits \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "prompt": "Make it look like a watercolor painting",
    "image": "https://example.com/photo.jpg"
  }'
```

### Response `200`

```json theme={null}
{
  "created": 1720000000,
  "data": [
    { "url": "https://cdn.hypergate.store/outputs/def456.png" }
  ],
  "usage": { "input_tokens": 8, "output_tokens": 0, "total_tokens": 8 }
}
```

| Field | Description |
| - | - |
| `created` | Unix timestamp of the request. |
| `data[0].url` | Generated or edited image URL. |
| `data[0].b64_json` | Base64-encoded image (only when `response_format: "b64_json"` is passed). |
| `usage` | Token usage for the request. |

***

## POST /v1/images (legacy)

Legacy alias for `POST /v1/images/generations`. Returns **HTTP 202** asynchronously — poll `GET /v1/images/{id}` for the result.

<Warning>
  This endpoint exists for backward compatibility. New integrations should use `POST /v1/images/generations` (text-to-image) or `POST /v1/images/edits` (image-to-image) — both return results synchronously with HTTP 200.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.