# Video Foreground Extractor — API Reference

Model ID: `model_birefnet-v2-video`

---

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

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `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'
{
  "model": "General Use (Light)",
  "operatingResolution": "1024x1024",
  "outputMask": false,
  "refineForeground": true,
  "videoQuality": "high",
  "videoWriteMode": "balanced"
}
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_birefnet-v2-video"
headers = {
    "Authorization": f"Basic {token}",
    "Content-Type": "application/json"
}
payload = {
    "model": "General Use (Light)",
    "operatingResolution": "1024x1024",
    "outputMask": False,
    "refineForeground": True,
    "videoQuality": "high",
    "videoWriteMode": "balanced"
}

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

**JavaScript**

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

const body = {
  "model": "General Use (Light)",
  "operatingResolution": "1024x1024",
  "outputMask": false,
  "refineForeground": true,
  "videoQuality": "high",
  "videoWriteMode": "balanced"
};

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

const data = await response.json();
console.log(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)*