> ## 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.

# Start Video Generation

> Start generating a video from a prompt, script, or media files

## Overview

This endpoint initiates video generation using various input methods. You can generate videos from text prompts, custom scripts, or by providing your own media files (voice, avatar, images).

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField body="prompt" type="string">
  Text prompt describing the video content. Required if no script is provided.
</ParamField>

<ParamField body="duration" type="number">
  Video duration in seconds (10-600). Required when using prompt.
</ParamField>

<ParamField body="script" type="string">
  Custom video script. Alternative to prompt-based generation.
</ParamField>

<ParamField body="voice_id" type="string">
  ID of the voice to use. Get available voices from `/voice/list` endpoint.
</ParamField>

<ParamField body="voice_url" type="string">
  URL to a custom voice file (audio format: mp3, wav, m4a).
</ParamField>

<ParamField body="avatar_id" type="string">
  ID of the avatar look to use. Get available avatars from `/avatar/list` endpoint.
</ParamField>

<ParamField body="avatar_url" type="string">
  URL to a custom avatar image/video file.
</ParamField>

<ParamField body="format" type="string" default="vertical">
  Video format: `vertical` (9:16), `square` (1:1), `ads` (4:5), `horizontal` (16:9), or `custom`.
</ParamField>

<ParamField body="width" type="number">
  Custom video width in pixels (max 5000). Only used when format is `custom`. Defaults to 1080.
</ParamField>

<ParamField body="height" type="number">
  Custom video height in pixels (max 5000). Only used when format is `custom`. Defaults to 1920.
</ParamField>

<ParamField body="media_urls" type="array">
  Array of URLs to media files (images, videos) to include in the video.
</ParamField>

<ParamField body="web_urls" type="array">
  Array of web URLs to extract content from (max 10).
</ParamField>

<ParamField body="web_search" type="object">
  <Expandable title="properties">
    <ParamField body="script" type="boolean" default="false">
      Enable web search for script generation.
    </ParamField>

    <ParamField body="images" type="boolean" default="false">
      Enable web search for relevant images.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="animate_image" type="boolean" default="false">
  Whether to animate static images using AI.
</ParamField>

<ParamField body="animate_image_max" type="number">
  Maximum number of images to animate.
</ParamField>

<ParamField body="emotion_enhancement" type="boolean" default="false">
  Enable emotion enhancement for more expressive voices.
</ParamField>

<ParamField body="use_native_avatar" type="boolean" default="false">
  Use a native avatar model (audio and video generated together) for a higher quality avatar. (The video won't have audio before the export.)
</ParamField>

<ParamField body="avatar_model" type="string" default="omni-flash">
  Native avatar model used to pre-split the video timeline like the export will (e.g. `omni-flash`, `veo-3-fast`, `seedance-2`). Only used when `use_native_avatar` is enabled.
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive webhook notifications when generation completes.
</ParamField>

<ParamField body="use_space_media" type="boolean" default="true">
  Whether to use media from your space library.
</ParamField>

<ParamField body="save_media_to_space" type="boolean" default="true">
  Whether to save generated media to your space library.
</ParamField>

<ParamField body="enable" type="object">
  Enable or disable specific video features.

  <Expandable title="properties">
    <ParamField body="subtitles" type="boolean" default="true">
      Enable adding automatic subtitles to the video.
    </ParamField>

    <ParamField body="broll" type="boolean" default="true">
      Enable automatically placing background images/videos.
    </ParamField>

    <ParamField body="music" type="boolean" default="true">
      Enable adding automatic background music that matches the video style.
    </ParamField>

    <ParamField body="transitions" type="boolean" default="true">
      Enable adding automatic transitions.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the generation job.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `pending`.
</ResponseField>

<ResponseField name="estimated_credits" type="number">
  Estimated credit cost for this generation.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/generation/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a video about sustainable energy solutions",
      "duration": 60,
      "voice_id": "voice_en_us_female_1",
      "avatar_id": "avatar_business_woman_1",
      "format": "vertical",
      "web_search": {
        "script": true,
        "images": true
      },
      "animate_image": true,
      "enable": {
        "subtitles": true,
        "broll": true,
        "music": true,
        "transitions": true
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/generation/start"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "prompt": "Create a video about sustainable energy solutions",
      "duration": 60,
      "voice_id": "voice_en_us_female_1",
      "avatar_id": "avatar_business_woman_1",
      "format": "vertical",
      "web_search": {
          "script": True,
          "images": True
      },
      "animate_image": True,
      "enable": {
          "subtitles": True,
          "broll": True,
          "music": True,
          "transitions": True
      }
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create a video about sustainable energy solutions",
      duration: 60,
      voice_id: "voice_en_us_female_1",
      avatar_id: "avatar_business_woman_1",
      format: "vertical",
      web_search: {
        script: true,
        images: true
      },
      animate_image: true,
      enable: {
        subtitles: true,
        broll: true,
        music: true,
        transitions: true
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "pending",
    "estimated_credits": 85
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_FIELD",
        "message": "Duration is required when using prompt",
        "field": "duration"
      }
    ]
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits. Required: 85, Available: 45",
    "code": "INSUFFICIENT_CREDITS"
  }
  ```
</ResponseExample>

## Input Methods

### 1. Prompt-based Generation

Provide a `prompt` and `duration`. The AI will generate a script and find relevant media.

### 2. Script-based Generation

Provide a custom `script` along with `voice_id` or `voice_url`.

### 3. Media-based Generation

Provide `voice_url` and/or `avatar_url` with custom media files.

## Credit Costs

Generation costs depend on several factors:

* **Base cost**: 5 credits every 30 seconds (with 15 seconds of buffer)
* **Image animation**: +5 credits per image

## Next Steps

1. **Monitor Progress**: Check status with `/generation/status/{job_id}`
2. **Export Video**: Use `/export/start` endpoint to export the video in the desired format
3. **Monitor Export Progress**: Check status with `/export/status/{job_id}`

## Error Codes

* `MISSING_CONTENT`: No prompt, script, voice\_url, or avatar\_url provided
* `MISSING_FIELD`: Required duration missing when using prompt
* `MISSING_VOICE`: No voice specified when using custom script
* `INSUFFICIENT_CREDITS`: Not enough credits available
* `INVALID_VOICE_ID`: Voice ID not found
* `INVALID_AVATAR_ID`: Avatar ID not found
* `INVALID_FORMAT`: Invalid video format