# Kling V3 I2V 4K — API Reference

Model ID: `model_kling-v3-i2v-4k`

---

## 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_kling-v3-i2v-4k`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | - | - | Text prompt for video generation. Either Prompt or Multi Prompt must be provided, but not both. |
| `multiPrompt` | object[] | - | - | Multi-shot prompts with per-shot durations. If provided, overrides the single prompt. Shot Type is required when using Multi Prompt. |
| `startImage` | assetId | yes | - | Image used as the first frame of the video. |
| `endImage` | assetId | - | - | Image used as the last frame of the video. |
| `duration` | string | - | `5` | The duration of the generated video in seconds. |
| `generateAudio` | boolean | - | `true` | Whether to generate native audio for the video. Supports Chinese and English voice output. Other languages are automatically translated to English. Billing is per second of video regardless of this setting. |
| `shotType` | string | - | `customize` | Multi-shot mode. Required when Multi Prompt is provided. |
| `cfgScale` | number | - | `0.5` | Higher values follow the prompt more closely, lower values are more creative. |
| `elements` | object[] | - | - | Elements (characters/objects) to include. Provide either images (frontal + reference) or a video for each element. Reference in prompt as @Element1, @Element2, etc. |
| `negativePrompt` | string | - | - | Negative prompt used to guide the model away from undesirable features. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_kling-v3-i2v-4k" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "startImage": "<asset_id>",
  "duration": "5",
  "generateAudio": true,
  "shotType": "customize",
  "cfgScale": 0.5
}
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_kling-v3-i2v-4k"
headers = {
    "Authorization": f"Basic {token}",
    "Content-Type": "application/json"
}
payload = {
    "startImage": "<asset_id>",
    "duration": "5",
    "generateAudio": True,
    "shotType": "customize",
    "cfgScale": 0.5
}

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

**JavaScript**

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

const body = {
  "startImage": "<asset_id>",
  "duration": "5",
  "generateAudio": true,
  "shotType": "customize",
  "cfgScale": 0.5
};

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

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