# Luma Uni-1 Max — API Reference

Model ID: `model_luma-uni-1-max`

---

## 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_luma-uni-1-max`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | yes | - | Describe the image you want to generate, or describe the changes you want to make when editing an existing image. Be specific about subject, style, mood, and composition for best results. |
| `source` | assetId | - | - | An existing image to edit. When provided, your prompt describes what to change rather than what to create. The output keeps the same aspect ratio unless you set one explicitly. |
| `imageRef` | assetId[] | - | `` | Reference images that guide the style or content of the output. Add up to 9 for generation, or up to 8 when editing (the source image occupies one slot). Each reference image adds a small cost. |
| `aspectRatio` | string | - | `3:2` | The width-to-height ratio of the generated image. Ignored when editing an existing image unless explicitly set. |
| `outputFormat` | string | - | `png` | File format of the generated image. PNG is lossless and supports transparency; JPEG is smaller and loads faster. |
| `webSearch` | boolean | - | `false` | When enabled, the model searches the web for relevant reference images before generating. Useful when your prompt refers to real-world subjects, places, or styles the model may not know well. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_luma-uni-1-max" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "prompt": "A fantasy landscape",
  "imageRef": [],
  "aspectRatio": "3:2",
  "outputFormat": "png",
  "webSearch": false
}
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",
    "imageRef": [],
    "aspectRatio": "3:2",
    "outputFormat": "png",
    "webSearch": False
}

response = client.generate.run_model(
    model_id="model_luma-uni-1-max",
    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",
  "imageRef": [],
  "aspectRatio": "3:2",
  "outputFormat": "png",
  "webSearch": false
};

const response = await client.generate.runModel("model_luma-uni-1-max", { 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)*