# GPT Image 2 — API Reference

Model ID: `model_openai-gpt-image-2`

---

## Authentication

Scenario API uses HTTP Basic Auth. Encode your credentials in Base64 and pass them as the `Authorization` header.

```
Authorization: Basic base64("<API_KEY>:<API_SECRET>")
```

- **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=project_api_keys) under API Keys.
- In shell: `$(echo -n '<API_KEY>:<API_SECRET>' | base64)`
- In JavaScript: `btoa("<API_KEY>:<API_SECRET>")`
- In Python: `base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()`

---

## Generate

**Endpoint:** `POST https://api.cloud.scenario.com/v1/generate/custom/model_openai-gpt-image-2`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | yes | - | Text description of desired generation or edit. |
| `referenceImages` | assetId[] | - | - | Reference images for editing. |
| `mask` | assetId | - | - | Mask image for inpainting. The image to edit and the mask must use the same format and dimensions. The mask must include an alpha channel—if you create the mask in an image editor, export or save it with alpha preserved. |
| `numOutputs` | number | - | `1` | Number of images to generate |
| `width` | number | - | - | Output width in pixels. |
| `height` | number | - | - | Output height in pixels. |
| `quality` | string | - | `auto` | Generation quality |
| `background` | string | - | `auto` | Background option |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_openai-gpt-image-2" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "prompt": "A fantasy landscape",
  "numOutputs": 1,
  "quality": "auto",
  "background": "auto"
}
EOF
```

**Python**

```python
import requests
import base64

api_key = "<API_KEY>"
api_secret = "<API_SECRET>"
token = base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()

url = "https://api.cloud.scenario.com/v1/generate/custom/model_openai-gpt-image-2"
headers = {
    "Authorization": f"Basic {token}",
    "Content-Type": "application/json"
}
payload = {
    "prompt": "A fantasy landscape",
    "numOutputs": 1,
    "quality": "auto",
    "background": "auto"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**JavaScript**

```javascript
const token = btoa("<API_KEY>:<API_SECRET>");

const body = {
  "prompt": "A fantasy landscape",
  "numOutputs": 1,
  "quality": "auto",
  "background": "auto"
};

const response = await fetch(
  "https://api.cloud.scenario.com/v1/generate/custom/model_openai-gpt-image-2",
  {
    method: "POST",
    headers: {
      "Authorization": `Basic ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  }
);

const data = await response.json();
console.info(data);
```

---

## Retrieve Results

After submitting a generation request, you receive a `jobId`. Poll the job status endpoint until the job completes.

**Endpoint:** `GET https://api.cloud.scenario.com/v1/jobs/{jobId}`

**Headers:**
```
Authorization: Basic base64("<API_KEY>:<API_SECRET>")
```

Poll until `job.status` is `"success"`. The generated asset IDs are in `job.metadata.assetIds`.

**Example response:**
```json
{
  "job": {
    "jobId": "job_abc123",
    "status": "success",
    "metadata": {
      "assetIds": [
        "asset_abc123"
      ]
    }
  }
}
```

> **Important:** Generated asset URLs are **temporary** and expire after a short period. Download and store any images you wish to keep before the URL expires. More info: [Content Delivery Network (CDN)](https://docs.scenario.com/docs/content-delivery-network-cdn).

---

*Generated by [Scenario](https://app.scenario.com)*