# Video Foreground Extractor — API Reference

Model ID: `model_birefnet-v2-video`

---

## 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_birefnet-v2-video`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video` | assetId | yes | - | Video to remove background from |
| `model` | string | - | `General Use (Light)` | Model to use for background removal. The 'General Use (Light)' model is the original model used in the BiRefNet repository. The 'General Use (Light)' model is the original model used in the BiRefNet repository but trained with 2K images. The 'General Use (Heavy)' model is a slower but more accurate model. The 'Matting' model is a model trained specifically for matting images. The 'Portrait' model is a model trained specifically for portrait images. The 'General Use (Light)' model is recommended for most use cases. |
| `operatingResolution` | string | - | `1024x1024` | The resolution to operate on. The higher the resolution, the more accurate the output will be for high res input images. |
| `outputMask` | boolean | - | `false` | Whether to output the mask used to remove the background |
| `refineForeground` | boolean | - | `true` | Refine the foreground for better results |
| `videoQuality` | string | - | `high` | Video output quality |
| `videoWriteMode` | string | - | `balanced` | Video write mode for encoding |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_birefnet-v2-video" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "video": "<asset_id>",
  "model": "General Use (Light)",
  "operatingResolution": "1024x1024",
  "outputMask": false,
  "refineForeground": true,
  "videoQuality": "high",
  "videoWriteMode": "balanced"
}
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 = {
    "video": "<asset_id>",
    "model": "General Use (Light)",
    "operatingResolution": "1024x1024",
    "outputMask": False,
    "refineForeground": True,
    "videoQuality": "high",
    "videoWriteMode": "balanced"
}

response = client.generate.run_model(
    model_id="model_birefnet-v2-video",
    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 = {
  "video": "<asset_id>",
  "model": "General Use (Light)",
  "operatingResolution": "1024x1024",
  "outputMask": false,
  "refineForeground": true,
  "videoQuality": "high",
  "videoWriteMode": "balanced"
};

const response = await client.generate.runModel("model_birefnet-v2-video", { 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)*