# Image to Layers — API Reference

Model ID: `model_scenario-image-layers-extractor`

---

## Authentication

- **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=project_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-image-layers-extractor`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `image` | assetId | yes | - | The image you want to separate into layers. |
| `separationInstruction` | string | yes | - | Tell the tool how to divide the image — describe the objects or the rule for splitting them, not the scene itself. For example: 'isolate the main subject', 'extract every object on the table', or 'separate each person from their clothes'. |
| `maxLayers` | number | - | `6` | The most layers the tool will produce. It may stop sooner if it decides nothing else is worth separating, or if it can't find the objects you described. More layers means a higher cost. The result will be your layers + the background. |
| `inpaintModel` | string | - | `gpt-image-2` | After each layer is cut out it leaves a hole in the background; this picks the AI that fills those holes back in. FLUX.2 Klein 9b is the fastest, FLUX.2 Dev is slower but higher quality, and GPT Image 2 uses OpenAI's model. This affects the cost. |
| `inpaintPrompt` | string | - | - | Optional extra guidance for filling in the background holes — e.g. a note about what the background should look like. Leave blank to use the default. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_scenario-image-layers-extractor" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "image": "<asset_id>",
  "separationInstruction": "A fantasy landscape",
  "maxLayers": 6,
  "inpaintModel": "gpt-image-2"
}
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 = {
    "image": "<asset_id>",
    "separationInstruction": "A fantasy landscape",
    "maxLayers": 6,
    "inpaintModel": "gpt-image-2"
}

response = client.generate.run_model(
    model_id="model_scenario-image-layers-extractor",
    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 = {
  "image": "<asset_id>",
  "separationInstruction": "A fantasy landscape",
  "maxLayers": 6,
  "inpaintModel": "gpt-image-2"
};

const response = await client.generate.runModel("model_scenario-image-layers-extractor", { 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)*