> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.video/llms.txt
> Use this file to discover all available pages before exploring further.
# Video Generation
> Learn how to generate videos with the Hoox API
## How Video Generation Works
The Hoox API uses advanced AI to generate videos from various inputs:
1. **Content Creation**: From prompts, scripts, or existing media
2. **Voice Synthesis**: Convert text to natural-sounding speech
3. **Visual Assembly**: Combine media, animations, and transitions
4. **Final Rendering**: Export in your desired format
## Generation Methods
Generate videos from simple text prompts. The AI creates the script, finds media, and assembles everything.
Provide your own script and let the AI handle voice synthesis and media selection.
Use your own voice recordings or avatar videos as the foundation.
Provide a ready-made editing plan and Hoox assembles the video exactly as described, sequence by sequence.
## Input Options
### Text Content
Generate videos using text-based inputs. These options are perfect when you want the AI to handle voice synthesis and media selection automatically.
#### Prompt
Provide a simple text prompt and let the AI create everything from scratch - script, media selection, and voice synthesis. Perfect for quick content creation.
```json theme={null}
{
"prompt": "Create an educational video about renewable energy sources, focusing on solar and wind power",
"voice_id": "en-US-JennyNeural"
}
```
#### Script
Provide your own detailed script and let the AI handle voice synthesis and media selection. Ideal when you want control over the narrative but need help with production.
```json theme={null}
{
"script": "Solar energy is one of the most promising renewable energy sources. It harnesses the power of the sun through photovoltaic cells...",
"voice_id": "en-US-AriaNeural",
}
```
### Media Content
Use your own media assets as the foundation for video generation. These options give you more control over the visual and audio elements of your videos.
#### Voice Recording
Use your own voice recordings as the audio track.
```json theme={null}
{
"voice_url": "https://your-domain.com/voiceover.mp3"
}
```
#### Avatar Video
Start with an existing avatar video where someone is speaking.
```json theme={null}
{
"avatar_url": "https://your-domain.com/avatar-speaking.mp4"
}
```
#### Custom Media
The AI will automatically analyze and place your media throughout the video based on the content.
```json theme={null}
{
"prompt": "A vide oabout my product",
"voice_id": "en-US-DavisNeural",
"media_urls": [
"https://your-domain.com/product-shot.jpg",
"https://your-domain.com/demo-video.mp4"
]
}
```
### Plan Content
Provide a ready-made **editing plan** and skip the AI montage entirely. Instead of letting Hoox decide how the video is cut, which media appears when, and which avatar look is on screen, you describe the montage yourself — sequence by sequence. This is ideal when an agent (or your own app) already knows exactly what the video should look like but shouldn't have to learn how to edit.
When a `sequence_plan` is provided it **takes precedence over everything else**. The video is assembled exactly as planned and `prompt` / `script` are ignored. Everything the plan does *not* specify (word timings, subtitles, music, transitions, and missing B-roll) still stays automatic.
The `sequence_plan` is a **flat array of speech blocks** in playback order. It has two levels:
* **Each array entry is a speech block** — one speaker talking continuously (one voice, one parent avatar, one audio track). A block is either fully spoken or fully silent, and its audio index is derived automatically from its position in the array.
* **`sequences`** — the visual fragments inside a block, in playback order. Each one carries a bit of `text`, and optionally its own media and avatar look.
Split a longer video into **several blocks**, don't cram everything into one. Each block is one continuous take by one speaker, so start a new block whenever the speaker, voice, or avatar changes — and, for longer monologues, break the speech into a handful of blocks rather than a single giant one.
**Defaults keep plans small.** The generation-level `voice_id` and `avatar_id` are used as the defaults for every block and sequence. You only set `voice_id`, `avatar_id`, or `look_id` inside the plan when a specific block or sequence needs to *override* the default — for example a different speaker's voice, or the same person shot in a different look on one sequence.
```json theme={null}
{
"voice_id": "voice_en_us_female_1",
"avatar_id": "look_default",
"sequence_plan": [
{
"sequences": [
{ "text": "We waste 3 hours a day.", "media": { "asset_id": "65f0a1b2c3d4e5f6a7b8c9d0", "show": "full" } },
{ "text": "Without even noticing.", "look_id": "look_closeup" }
]
},
{
"voice_id": "voice_en_us_male_1",
"look_id": "look_second_speaker",
"sequences": [
{ "text": "Oh yeah? How come?", "media": { "url": "https://your-domain.com/chart.jpg", "show": "half" } }
]
}
]
}
```
**Media** can reference an `asset_id` from your space library or a public `url`, and `show` controls how it covers the avatar (`full`, `half`, `background`, or `hide`). To insert a pause, add a dedicated block with a single silent sequence: `{ "text": null, "duration_ms": 1200 }`.
Never provide timings for spoken text — Hoox always computes word timings from the generated audio. `duration_ms` is only for silent sequences.
See the [Start Video Generation reference](/api-reference/generation/start) for the full `sequence_plan` schema.
## Advanced Features
### Custom Video Formats
Create videos with custom dimensions tailored to your specific needs. Beyond the standard formats (vertical, square, ads, horizontal), you can specify exact width and height dimensions.
```json theme={null}
{
"prompt": "Create a product showcase video",
"voice_id": "en-US-DavisNeural",
"format": "custom",
"width": 1200,
"height": 1600
}
```
Custom dimensions support up to 5000px for both width and height, allowing you to create videos for any platform or display requirement.
### Web Search Integration
Enhance your videos with real-time web content. The AI can search the internet during script writing to include current information, or find relevant images like celebrity photos, landmarks, content to enrich your video.
```json theme={null}
{
"prompt": "Explain cryptocurrency basics",
"voice_id": "en-US-JennyNeural",
"webSearch": {
"script": true, // Enhance script with web research
"images": true // Find relevant images automatically
}
}
```
### Image Animation
Transform static images into dynamic videos using AI animation. Images from URLs are automatically converted into animated sequences, bringing still photos to life with natural movement and transitions.
```json theme={null}
{
"script": "The landscape shows beautiful mountains...",
"voice_id": "en-US-AriaNeural",
"animate_image": true,
"animate_image_max": 3 // Limit for cost control
}
```
Use the `animate_image_max` parameter to control animation costs when using many images.
### Workspace Media Control
Control how workspace media is used:
```json theme={null}
{
"prompt": "Create a company overview video",
"voice_id": "en-US-DavisNeural",
"use_space_media": false, // Don't use workspace media
"save_media_to_space": false // Don't save generated media
}
```
## Next Steps
Learn how to export your generated videos
Detailed API documentation for video generation