Skip to main content
POST
/
api
/
public
/
v1
/
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,
    "animate_mode": "pro"
  }'

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

​
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

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

​
Request Body

​
prompt
string
Text prompt describing the video content. Required if no script is provided.
​
duration
number
Video duration in seconds (10-600). Required when using prompt.
​
script
string
Custom video script. Alternative to prompt-based generation.
​
voice_id
string
ID of the voice to use. Get available voices from /resources/voices endpoint.
​
voice_url
string
URL to a custom voice file (audio format: mp3, wav, m4a).
​
avatar_id
string
ID of the avatar look to use. Get available avatars from /resources/avatars endpoint.
​
avatar_url
string
URL to a custom avatar image/video file.
​
format
string
default:"vertical"
Video format: vertical (9:16), square (1:1), or ads (16:9).
​
media_urls
array
Array of URLs to media files (images, videos) to include in the video.
​
web_urls
array
Array of web URLs to extract content from (max 10).
​
web_search
object
​
animate_image
boolean
default:"false"
Whether to animate static images using AI.
​
animate_mode
string
default:"standard"
Animation quality: standard or pro.
​
animate_image_max
number
Maximum number of images to animate.
​
webhook_url
string
URL to receive webhook notifications when generation completes.
​
use_space_media
boolean
default:"true"
Whether to use media from your space library.
​
save_media_to_space
boolean
default:"true"
Whether to save generated media to your space library.

​
Response

​
job_id
string
Unique identifier for the generation job.
​
status
string
Current job status: pending.
​
estimated_credits
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,
    "animate_mode": "pro"
  }'

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

​
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: +4 credits per image (standard) or +7 credits per image (pro mode)

​
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
  • INVALID_ANIMATE_MODE: Invalid animation mode
⌘I