---
title: Best Practices
url: https://docs.kaltura.com/docs/conversational-agents/avatar-videos/best-practices
---

## Best Practices

- **Generate the KS server-side.** The KS is visible in client-side code — generate it on your backend and pass it to the widget  
- **Set `partnerId` as a number.** The VOD Avatar widget requires `partnerId` as a number type (e.g., `12345` rather than `"12345"`)  
- **Ensure captions before composing.** Source entries need captions or transcripts for AI composition. Use REACH to add captions first  
- **Poll at 10-second intervals.** The widget uses 10-second polling; match this in server-side integrations  
- **Handle error states.** Use `resetStatus` to recover from `compose-error` or `generate-error`, then modify scenes and retry  
- **Preview audio before generating.** Use `previewAudio` to verify narration quality — generation is more expensive  
- **Reuse b-roll entries at different start times.** The same entry at different `startTime` offsets gives visual variety without adding sources. Prefer fewer entries with longer durations for maximum reuse  
- **Prepare b-roll entries.** Ensure all b-roll source videos use standard frame rates (25 or 30 fps). Re-encode PowerPoint exports and screen recordings before uploading. Kaltura's transcoding pipeline handles codec conversion and adds audio tracks automatically  
- **Write at least one full sentence per scene.** The API validates narration text at `video/add` time — provide at least one complete sentence (~4+ words) per scene to produce sufficient TTS audio (1.5+ seconds)  
- **Budget narration for b-roll scenes.** TTS speaks at ~2.4 words/second. For b-roll scenes, keep word count below `(clip_duration - startTime) × 2.1` to leave a safety margin. Use `previewAudio` and `ffprobe` to verify actual TTS duration for scenes close to the budget  
- **Use long KS expiry for generation.** Generation can take 10–20 minutes for complex videos. Use 86400s (24h) expiry to ensure the session remains valid throughout  
- **Process generated videos.** The resulting Kaltura entry can be enriched via REACH (captions, translation, chapters, summaries) or Agents (automated workflows)  
- **Use HTTPS.** The embeds loader and all widget bundles require HTTPS  

### Multi-Region CDN

| Region | Server-Side API | Widget URL |
|--------|----------------|------------|
| NVP1 (US East, default) | `https://video-avatar.nvp1.ovp.kaltura.com/api/v1` | `https://unisphere.nvp1.ovp.kaltura.com/v1` |
| IRP2 (EU West) | `https://video-avatar.irp2.ovp.kaltura.com/api/v1` | `https://unisphere.irp2.ovp.kaltura.com/v1` |
| FRP2 (EU Central) | `https://video-avatar.frp2.ovp.kaltura.com/api/v1` | `https://unisphere.frp2.ovp.kaltura.com/v1` |
| CAP2 (Canada) | `https://video-avatar.cap2.ovp.kaltura.com/api/v1` | `https://unisphere.cap2.ovp.kaltura.com/v1` |
| SGP2 (Singapore) | `https://video-avatar.sgp2.ovp.kaltura.com/api/v1` | `https://unisphere.sgp2.ovp.kaltura.com/v1` |
| SYP2 (Australia) | `https://video-avatar.syp2.ovp.kaltura.com/api/v1` | `https://unisphere.syp2.ovp.kaltura.com/v1` |