POST /v1/videos, then poll GET /v1/videos/{video_id} for the finished video. This H3 Video mode includes native audio and also accepts reference images, with or without a reference video.
What you need
- An API key from the Viggle Dashboard, exported as
VIGGLE_API_KEY. - Your reference video saved as
reference.mp4in the directory where you run the example. It must be 0.5–600 seconds long, at least 64×64 pixels, with even width and height. - For cURL, install
jq; for Node, use Node.js 20+ and save the example as an.mjsfile; for Python, installrequestswithpip install requests.
prompt to describe your desired shot. Both prompt and quality are required; use low for faster iteration or high for higher fidelity.
Generate and poll the video
Response
video_url when status is ready; they stop on failed, cancelled, or a polling timeout. If polling times out, you can resume with the same ID using Get Video.
Open the printed URL to view or download your video. The signed URL is valid for 1 hour; fetch Get Video again for a fresh link.
Use a URL or reference images
- Hosted video: replace
reference_videowithreference_video_urlcontaining your publicly reachable video URL. Supply at most one reference video across file uploads and URLs. - Add images: include
reference_imagefile uploads orreference_image_urlfields alongside the video. Repeat these fields for up to 4 images in total. - Images only: omit the video and supply at least one reference image. Keep
promptandquality.
Include at least one reference field; omitting all reference fields selects text-to-video generation. Do not combine reference fields with first/last-frame fields or Viggle-Animate’s driving-video and character-image fields.
duration_s controls the generated video’s length (3–15 seconds, default 5), independently of the reference video’s length. See Pricing and retention for generation costs.
Generate Video (from Reference Video/Image)
See every parameter, reference-image examples, and validation errors.
Using Viggle-Animate
Apply a driving video’s motion to character images.

