# Scenario Skybox GPT — API Reference

Model ID: `model_scenario-skybox-gpt`

---

## Authentication

- **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=api_keys) under API Keys.
- Set them as environment variables `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` — both SDKs pick them up by default.
- For raw HTTP (cURL), use Basic Auth: `Authorization: Basic base64("<API_KEY>:<API_SECRET>")`.

### Install the SDK

- JavaScript / TypeScript: `npm install @scenario-labs/sdk`
- Python: `pip install scenario-sdk`

---

## Generate

**Endpoint:** `POST https://api.cloud.scenario.com/v1/generate/custom/model_scenario-skybox-gpt`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | yes | - | Describe the scene you want to see all around you — a mountain pass at dusk, a cathedral interior, an alien landscape. The model automatically formats your prompt to produce a seamless 360° panorama. |
| `referenceImages` | assetId[] | - | - | Upload one or more images to guide the style, mood, or content of the skybox. The model draws inspiration from them while still following your prompt. Up to 10 images accepted. |
| `width` | number | - | `2048` | Width of the generated panorama in pixels, must be a multiple of 16. A 2:1 width-to-height ratio is recommended for correct 360° viewing. |
| `height` | number | - | `1024` | Height of the generated panorama in pixels, must be a multiple of 16. A 2:1 width-to-height ratio is recommended for correct 360° viewing. |
| `quality` | string | - | `high` | Controls the detail and generation time of the output. High produces the best results; Medium and Low are faster and more cost-efficient. Auto lets the model decide based on your input. |
| `seed` | number | - | - | A number that locks in the randomness of the generation. Copy the seed from a result you liked to reproduce it exactly, or leave blank for a new result each time. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_scenario-skybox-gpt" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "prompt": "A fantasy landscape",
  "width": 2048,
  "height": 1024,
  "quality": "high"
}
EOF
```

**Python**

```python
import os
from scenario_sdk import Scenario

client = Scenario(
    api_key=os.environ.get("SCENARIO_SDK_API_KEY"),
    api_secret=os.environ.get("SCENARIO_SDK_API_SECRET"),
)

body = {
    "prompt": "A fantasy landscape",
    "width": 2048,
    "height": 1024,
    "quality": "high"
}

response = client.generate.run_model(
    model_id="model_scenario-skybox-gpt",
    body=body,
)
print(response)
```

**JavaScript**

```javascript
import Scenario from "@scenario-labs/sdk";

const client = new Scenario({
  apiKey: process.env["SCENARIO_SDK_API_KEY"],
  apiSecret: process.env["SCENARIO_SDK_API_SECRET"],
});

const body = {
  "prompt": "A fantasy landscape",
  "width": 2048,
  "height": 1024,
  "quality": "high"
};

const response = await client.generate.runModel("model_scenario-skybox-gpt", { body });
console.info(response);
```

---

## Retrieve Results

After submitting a generation request, you receive a `jobId`. Poll the job until `job.status` is `"success"`. The generated asset IDs are in `job.metadata.assetIds`.

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

### Example Requests

**cURL**

```bash
curl -X GET "https://api.cloud.scenario.com/v1/jobs/<JOB_ID>" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)"
```

**Python**

```python
job = client.jobs.retrieve(job_id="<JOB_ID>")
print(job.status)
print(job.metadata.asset_ids)
```

**JavaScript**

```javascript
// Option 1 — wait on the response from runModel using the SDK helper
const completed = await response.job.wait();
console.info(completed.status);
console.info(completed.metadata?.assetIds);

// Option 2 — retrieve a job by its ID
const job = await client.jobs.retrieve("<JOB_ID>");
console.info(job.status);
console.info(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/get-started/documentation/content-delivery-network-cdn).

---

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