Skip to main content
Upload a reference video, describe the shot you want, and generate a new video that carries the reference’s subject or style. Submit one request to 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.mp4 in 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 .mjs file; for Python, install requests with pip install requests.
The examples upload your local file and request a 5-second output. Change the 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

The create request returns immediately with a video ID. The examples poll every 5 seconds and print 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_video with reference_video_url containing your publicly reachable video URL. Supply at most one reference video across file uploads and URLs.
  • Add images: include reference_image file uploads or reference_image_url fields 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 prompt and quality.
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.