# KlingAI Provider

KlingAI specializes in high-quality video generation with advanced features including text-to-video, image-to-video, start/end frame control, and motion control. Known for competitive pricing and professional-grade video output.

## Setup

### Installation

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/klingai"
)
```

### Configuration

The recommended path is a single API key, sent directly as a bearer token:

```go
provider, err := klingai.New(klingai.Config{
    APIKey: os.Getenv("KLINGAI_API_KEY"),
})

model, err := provider.VideoModel("kling-v2.6-t2v")
```

```bash
export KLINGAI_API_KEY=...
```

The legacy access-key/secret-key pair (which signs a short-lived JWT per
request) is still supported and used when `APIKey` is unset:

```go
provider, err := klingai.New(klingai.Config{
    AccessKey: os.Getenv("KLINGAI_ACCESS_KEY"),
    SecretKey: os.Getenv("KLINGAI_SECRET_KEY"),
})
```

```bash
export KLINGAI_ACCESS_KEY=your-access-key
export KLINGAI_SECRET_KEY=your-secret-key
```

Credentials are resolved on every request rather than once in `New()`, so
changing the environment variables takes effect without rebuilding the
provider.

## Available Models

### Text-to-Video Models

| Model ID | Quality | Speed | Duration | Best For |
|----------|---------|-------|----------|----------|
| kling-v2.6-t2v | Excellent | Medium | 5-10s | Latest quality |
| kling-v2.5-turbo-t2v | Good | Fast | 5-10s | Speed optimized |
| kling-v2.1-master-t2v | High | Medium | 5-10s | Stable version |
| kling-v1.6-t2v | Good | Fast | 5s | Legacy support |

### Image-to-Video Models

| Model ID | Quality | Speed | Features | Best For |
|----------|---------|-------|----------|----------|
| kling-v2.6-i2v | Excellent | Medium | Start/end control | Professional work |
| kling-v2.5-turbo-i2v | Good | Fast | Basic animation | Quick animations |
| kling-v2.1-master-i2v | High | Medium | Advanced control | Production quality |

### Motion Control Models

| Model ID | Quality | Speed | Max Reference | Best For |
|----------|---------|-------|---------------|----------|
| kling-v2.6-motion-control | High | Slow | 30s (pro) / 10s (std) | Motion transfer |
| kling-v3.0-motion-control | Highest | Slow | 30s (pro) / 10s (std) | Latest motion transfer |

## Provider-Specific Features

### Text-to-Video Generation

Create videos from text descriptions:

```go
model, _ := provider.VideoModel("kling-v2.6-t2v")

duration := 10.0
result, err := ai.GenerateVideo(ctx, ai.GenerateVideoOptions{
    Model:       model,
    Prompt:      ai.VideoPrompt{Text: "A sunrise over mountains in 4K"},
    Duration:    &duration,
    AspectRatio: "16:9",
    ProviderOptions: map[string]interface{}{
        "klingai": map[string]interface{}{
            "mode": "pro",
            "negativePrompt": "low quality, blurry",
        },
    },
})
```

### Image-to-Video Animation

Animate static images with camera control:

```go
model, _ := provider.VideoModel("kling-v2.6-i2v")

result, err := ai.GenerateVideo(ctx, ai.GenerateVideoOptions{
    Model: model,
    Prompt: ai.VideoPrompt{
        Image: &ai.VideoPromptImage{Data: imageData},
        Text: "The cat slowly turns its head and blinks",
    },
    Duration: &duration,
    ProviderOptions: map[string]interface{}{
        "klingai": map[string]interface{}{
            "mode": "pro",
            "cameraControl": map[string]interface{}{
                "type": "forward_up",
                "config": map[string]interface{}{
                    "horizontal": 0.5,
                    "vertical": 0.3,
                    "zoom": 0.2,
                },
            },
        },
    },
})
```

### Start/End Frame Control

Precise control over video start and end states:

```go
model, _ := provider.VideoModel("kling-v2.6-i2v")

result, err := ai.GenerateVideo(ctx, ai.GenerateVideoOptions{
    Model: model,
    Prompt: ai.VideoPrompt{
        Image: &ai.VideoPromptImage{Data: startImage},
        Text: "Transform cat into dog with smooth transition",
    },
    ProviderOptions: map[string]interface{}{
        "klingai": map[string]interface{}{
            "mode": "pro", // Required for start/end control
            "imageTail": endImageURL,
            "sound": "on",
        },
    },
})
```

### Motion Control

Transfer motion from reference videos to your characters:

```go
model, _ := provider.VideoModel("kling-v2.6-motion-control")

result, err := ai.GenerateVideo(ctx, ai.GenerateVideoOptions{
    Model: model,
    Prompt: ai.VideoPrompt{
        Image: &ai.VideoPromptImage{Data: characterImage},
        Text: "Character performs smooth dance move",
    },
    ProviderOptions: map[string]interface{}{
        "klingai": map[string]interface{}{
            "videoUrl": "https://example.com/reference-motion.mp4",
            "characterOrientation": "video", // "image" or "video"
            "mode": "pro",
            "keepOriginalSound": "yes",
            "pollTimeoutMs": 600000, // 10 minutes for pro mode
        },
    },
})
```

## Provider Options

Configure generation with `ProviderOptions.klingai`:

### Common Options

| Option | Type | Description | Modes |
|--------|------|-------------|-------|
| `mode` | string | `"std"` or `"pro"` quality mode | All |
| `pollIntervalMs` | int | Polling interval (default: 5000ms) | All |
| `pollTimeoutMs` | int | Max wait time (default: 600000ms) | All |

### Text-to-Video & Image-to-Video Options

| Option | Type | Description |
|--------|------|-------------|
| `negativePrompt` | string | What to avoid (max 2500 chars) |
| `sound` | string | `"on"` or `"off"` (V2.6+ pro only) |
| `cfgScale` | float64 | Prompt adherence 0.0-1.0 (V1.x only) |

### Camera Control

```go
"cameraControl": map[string]interface{}{
    "type": "forward_up", // simple, down_back, right_turn_forward, left_turn_forward
    "config": map[string]interface{}{
        "horizontal": 0.5, // -1.0 to 1.0
        "vertical": 0.3,   // -1.0 to 1.0
        "zoom": 0.2,       // -1.0 to 1.0
    },
}
```

### Image-to-Video Specific

| Option | Type | Description |
|--------|------|-------------|
| `imageTail` | string | End frame image URL or base64 |
| `staticMask` | string | Static brush mask image |
| `dynamicMasks` | array | Dynamic brush configurations |

### Motion Control Specific

| Option | Type | Description |
|--------|------|-------------|
| `videoUrl` | string | Reference video URL (required) |
| `characterOrientation` | string | `"image"` or `"video"` (required) |
| `keepOriginalSound` | string | `"yes"` or `"no"` |
| `watermarkEnabled` | bool | Enable watermark |

## Examples

### Basic Text-to-Video

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/provider"
    "github.com/digitallysavvy/go-ai/pkg/providers/klingai"
)

func main() {
    prov, err := klingai.New(klingai.Config{
        APIKey: os.Getenv("KLINGAI_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }

    model, err := prov.VideoModel("kling-v2.6-t2v")
    if err != nil {
        log.Fatal(err)
    }

    duration := 5.0
    result, err := model.DoGenerate(context.Background(),
        &provider.VideoModelV3CallOptions{
            Prompt: "A sunrise over mountains",
            Duration: &duration,
            AspectRatio: "16:9",
        })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Video URL: %s\n", result.Videos[0].URL)
}
```

See `examples/providers/klingai/` for more complete examples including:
- Image-to-video with camera control
- Start/end frame control
- Motion control (standard and pro)

## Async Video

`VideoModel` also implements `provider.VideoModelStarter` /
`VideoModelStatusChecker`, so it works with `ai.ExperimentalStartVideo` /
`ai.ExperimentalGetVideoStatus` in addition to the polling `ai.GenerateVideo`.

## Polling Behavior

KlingAI video generation is asynchronous with automatic polling:

- **Default interval:** 5 seconds
- **Default timeout:** 10 minutes
- **Configurable** via provider options

```go
ProviderOptions: map[string]interface{}{
    "klingai": map[string]interface{}{
        "pollIntervalMs": 3000,  // Poll every 3 seconds
        "pollTimeoutMs": 300000, // 5 minute timeout
    },
}
```

## Error Handling

Common error scenarios:

```go
result, err := model.DoGenerate(ctx, opts)
if err != nil {
    if klingErr, ok := err.(*klingai.Error); ok {
        switch klingErr.Code {
        case 401:
            log.Println("Authentication failed")
        case 504:
            log.Println("Generation timeout")
        default:
            log.Printf("KlingAI error %d: %s", klingErr.Code, klingErr.Message)
        }
    }
    return err
}
```

## Best Practices

1. **Use Pro Mode for Quality**
   - Better visual quality
   - Required for start/end frame control
   - Supports audio generation (V2.6+)

2. **Optimize Polling**
   - Use longer intervals for pro mode
   - Set appropriate timeouts (5-10 minutes)
   - Handle timeout errors gracefully

3. **Motion Control Tips**
   - Use clear, well-lit reference videos
   - Match character orientation correctly
   - Pro mode supports longer references (up to 30s)

4. **Prompting**
   - Be specific and detailed
   - Use negative prompts to avoid unwanted elements
   - Test different camera controls for best results

## Limitations

- **Resolution:** Not configurable (determined by model/image)
- **FPS:** Not configurable
- **Seed:** Not supported for deterministic generation
- **Max videos per call:** 1
- **Max duration:** 10 seconds (standard), varies by model

Attempting unsupported options will generate warnings but not fail.

## Rate Limits & Pricing

### Rate Limits

- **Token Generation:** 100 requests/minute
- **Video Generation:** 10 concurrent tasks per account
- **Polling:** No explicit limit (use backoff)

### Pricing

Contact KlingAI for current pricing information. Pricing varies by:
- Model version (V1, V2, V2.5, V2.6)
- Quality mode (standard vs pro)
- Video duration (5s vs 10s)

## See Also

- [API Reference: GenerateVideo](https://goaisdk.com/docs/ai-sdk-core/video-generation.md)
- [Examples: KlingAI](https://github.com/digitallysavvy/go-ai/tree/main/examples/providers/klingai)
- [KlingAI API Documentation](https://app.klingai.com/global/dev/document-api)
- [KlingAI Model Capabilities](https://app.klingai.com/global/dev/document-api/apiReference/model/skillsMap)