Start Video Generation

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
    }
  }'

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())

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);

{
  "job_id": "run_abcd1234",
  "status": "pending",
  "estimated_credits": 85
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "MISSING_FIELD",
      "message": "Duration is required when using prompt",
      "field": "duration"
    }
  ]
}

{
  "error": "Insufficient credits. Required: 85, Available: 45",
  "code": "INSUFFICIENT_CREDITS"
}

POST

api

public

generation

start

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
    }
  }'

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())

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);

{
  "job_id": "run_abcd1234",
  "status": "pending",
  "estimated_credits": 85
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "MISSING_FIELD",
      "message": "Duration is required when using prompt",
      "field": "duration"
    }
  ]
}

{
  "error": "Insufficient credits. Required: 85, Available: 45",
  "code": "INSUFFICIENT_CREDITS"
}

Overview

This endpoint initiates video generation using various input methods. You can generate videos from text prompts, custom scripts, by providing your own media files (voice, avatar, images), or from a ready-made editing plan (sequence_plan) that controls the montage sequence by sequence.

Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header.

Request Body

string

Text prompt describing the video content. Required if no script is provided.

number

Video duration in seconds (10-600). Required when using prompt.

string

Custom video script. Alternative to prompt-based generation.

string

ID of the voice to use. Get available voices from /voice/list endpoint.

string

URL to a custom voice file (audio format: mp3, wav, m4a).

string

ID of the avatar look to use. Get available avatars from /avatar/list endpoint.

string

URL to a custom avatar image/video file.

string

default:"vertical"

Video format: vertical (9:16), square (1:1), ads (4:5), horizontal (16:9), or custom.

number

Custom video width in pixels (max 5000). Only used when format is custom. Defaults to 1080.

number

Custom video height in pixels (max 5000). Only used when format is custom. Defaults to 1920.

array

Array of URLs to media files (images, videos) to include in the video.

array

Array of web URLs to extract content from (max 10).

object

Show properties

boolean

default:"false"

Enable web search for script generation.

boolean

default:"false"

Enable web search for relevant images.

boolean

default:"false"

Whether to animate static images using AI.

number

Maximum number of images to animate.

boolean

default:"false"

Enable emotion enhancement for more expressive voices.

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

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-5). Only used when use_native_avatar is enabled.

string

URL to receive webhook notifications when generation completes.

boolean

default:"true"

Whether to use media from your space library.

boolean

default:"true"

Whether to save generated media to your space library.

object

Enable or disable specific video features.

Show properties

boolean

default:"true"

Enable adding automatic subtitles to the video.

boolean

default:"true"

Enable automatically placing background images/videos.

boolean

default:"true"

Enable adding automatic background music that matches the video style.

boolean

default:"true"

Enable adding automatic transitions.

array

A ready-made editing plan: a flat array of speech blocks describing the montage sequence by sequence. When provided, it takes precedence over prompt and script. See the Plan Content guide for the concepts.

Show speech block properties

array

required

Visual fragments of this speech block, in playback order.

Show sequence properties

string | null

required

Text spoken during this visual fragment. Use null for a silent sequence (then duration_ms is required and the sequence must be alone in a dedicated silent block).

number

Fixed duration in milliseconds. Only for silent sequences (text: null) — spoken sequences are always timed from the generated audio.

string

Avatar look override for this sequence only. Defaults to the block’s look, then to the request-level avatar_id.

string

What the avatar does while speaking this sequence, in plain language (e.g. He frowns thoughtfully and touches his chin). Applied at export by the avatar models that accept motion direction (the native models and premium).

object

Media displayed during this sequence. Omit it to let automatic B-roll fill the slot (only happens when no sequence of the whole plan carries a media).

Show media properties

string

Media id from your space library. Takes precedence over url.

string

Public URL of an image or video to display.

string

default:"hide"

How the media is displayed relative to the avatar: full (covers the whole frame), half (split with the avatar), background (behind the avatar on green screen), or hide (attached but not shown).

number

For videos: trim the source to start at this time (in seconds).

string

Voice for this whole block. Falls back to the request-level voice_id. Ignored for silent blocks.

string

Pre-recorded audio URL for this block — skips voice generation for it.

string

Parent avatar of this block. Falls back to the request-level avatar_id.

string

Default avatar look for this block’s sequences.

Response

string

Unique identifier for the generation job.

string

Current job status: pending.

number

Estimated credit cost for this generation.

Example

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
    }
  }'

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())

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);

{
  "job_id": "run_abcd1234",
  "status": "pending",
  "estimated_credits": 85
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "MISSING_FIELD",
      "message": "Duration is required when using prompt",
      "field": "duration"
    }
  ]
}

{
  "error": "Insufficient credits. Required: 85, Available: 45",
  "code": "INSUFFICIENT_CREDITS"
}

Plan-based Example

This request generates a two-speaker video from a ready-made plan. The top-level voice_id and avatar_id are the defaults; the second block overrides them with a different voice and look, and one sequence swaps to a close-up look and directs the avatar with an action.

cURL

curl -X POST "https://app.hoox.video/api/public/v1/generation/start" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "voice_en_us_female_1",
    "avatar_id": "look_default",
    "format": "vertical",
    "sequence_plan": [
      {
        "sequences": [
          {
            "text": "We waste 3 hours a day.",
            "media": { "asset_id": "65f0a1b2c3d4e5f6a7b8c9d0", "show": "full" }
          },
          {
            "text": "Without even noticing.",
            "look_id": "look_closeup",
            "action": "He shakes his head slowly"
          }
        ]
      },
      {
        "sequences": [
          { "text": null, "duration_ms": 1200 }
        ]
      },
      {
        "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" }
          }
        ]
      }
    ]
  }'

The silent pause ({ "text": null, "duration_ms": 1200 }) sits in its own block with no voice_id — that is required for every silent sequence.

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.

4. Plan-based Generation

Provide a sequence_plan — a flat array of speech blocks — describing the montage sequence by sequence. This takes precedence over prompt and script: the video is assembled exactly as planned. The request-level voice_id / avatar_id act as defaults for blocks and sequences that don’t override them. See the Plan Content guide for the concepts.

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

Monitor Progress: Check status with /generation/status/{job_id}
Export Video: Use /export/start endpoint to export the video in the desired format
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
INVALID_PLAN: The sequence_plan failed schema validation (the offending field is returned in details)
PLAN_RESOLUTION_FAILED: A voice_id, avatar_id, or look_id referenced in the plan could not be found in your space

Script

Generation

Export

Avatar

Voices

Folder

Assets

Overview

Authentication

Request Body

Response

Example

Plan-based Example

Input Methods

1. Prompt-based Generation

2. Script-based Generation

3. Media-based Generation

4. Plan-based Generation

Credit Costs

Next Steps

Error Codes

​Overview

​Authentication

​Request Body

​Response

​Example

​Plan-based Example

​Input Methods

​1. Prompt-based Generation

​2. Script-based Generation

​3. Media-based Generation

​4. Plan-based Generation

​Credit Costs

​Next Steps

​Error Codes

Overview

Authentication

Request Body

Response

Example

Plan-based Example

Input Methods

1. Prompt-based Generation

2. Script-based Generation

3. Media-based Generation

4. Plan-based Generation

Credit Costs

Next Steps

Error Codes