# Seedance 2.5 — API Reference

Model ID: `model_bytedance-seedance-2-5`

---

## 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_bytedance-seedance-2-5`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | - | - | Describe the video you want. Use "@" such as "@image1" or "@video1" to reference uploads. Mode is inferred from your inputs and prompt: text-to-video, first/last frame, reference-to-video, editing, or extension. Optional if you provide a first frame or reference images/videos/audio. |
| `image` | assetId | - | - | First frame for image-to-video. Mutually exclusive with reference images/videos. In first/last-frame mode, aspect ratio is ignored (always adaptive to this frame). |
| `lastFrameImage` | assetId | - | - | Optional last frame. Only valid when a first frame is provided. |
| `referenceImages` | assetId[] | - | - | Reference images for multimodal / reference-to-video mode (up to 30). Mutually exclusive with first frame. To control the opening and closing shots anyway, add those frames here and say which is which in the prompt, for example "@image1 is the first frame, @image2 is the last frame". |
| `referenceVideos` | assetId[] | - | - | Reference videos for multimodal, editing, or extension mode (up to 10, each 2–30s, 30s combined). Mutually exclusive with first frame. Editing and extension are inferred from your prompt. |
| `referenceAudio` | assetId[] | - | - | Reference audio tracks (up to 10). Can be used alone, or with reference images/videos. |
| `duration` | number | - | `-1` | How long the video lasts, in seconds (4-30), or Auto. With reference videos, Auto matches the longest reference clip (kept within 4-30s). Ignored in editing mode (must be Auto / -1; output follows the input video). |
| `resolution` | string | - | `720p` | The output quality. Higher resolution is sharper but costs more. Ignored when Draft is on (output is 480p). |
| `aspectRatio` | string | - | `adaptive` | The shape of the video. Auto picks a fitting shape based on your inputs. Ignored in first/last-frame mode, editing mode, and extension mode (always adaptive to the input). |
| `generateAudio` | boolean | - | `true` | Adds a generated soundtrack to the video. |
| `outputFormat` | string | - | `mp4` | Video container format. MP4 is the general-purpose delivery format; MOV keeps higher colour fidelity for grading and compositing (larger files, narrower player support). |
| `draft` | boolean | - | `false` | When on, render a cheap 480p preview that can be finalized to 1080p later without re-generating. The 480p output stays valid for 7 days. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_bytedance-seedance-2-5" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "duration": -1,
  "resolution": "720p",
  "aspectRatio": "adaptive",
  "generateAudio": true,
  "outputFormat": "mp4",
  "draft": 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 = {
    "duration": -1,
    "resolution": "720p",
    "aspectRatio": "adaptive",
    "generateAudio": True,
    "outputFormat": "mp4",
    "draft": False
}

response = client.generate.run_model(
    model_id="model_bytedance-seedance-2-5",
    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 = {
  "duration": -1,
  "resolution": "720p",
  "aspectRatio": "adaptive",
  "generateAudio": true,
  "outputFormat": "mp4",
  "draft": false
};

const response = await client.generate.runModel("model_bytedance-seedance-2-5", { 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)*