Generate Video (from Character Animation)

Generate a video from text, from a first and optional last frame, from a reference video/image, or from a character image and/or driving video

curl --request POST \
  --url https://apis.viggle.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=A paper airplane gliding through a sunlit office' \
  --form quality=low \
  --form first_frame_image='@example-file' \
  --form 'first_frame_image_url=<string>' \
  --form last_frame_image='@example-file' \
  --form 'last_frame_image_url=<string>' \
  --form 'reference_video=<string>' \
  --form 'reference_video_url=<string>' \
  --form 'reference_image=<string>' \
  --form 'reference_image_url=<string>' \
  --form 'driving_video_url=<string>' \
  --form 'character_image_url=<string>' \
  --form 'character_image_urls=<string>' \
  --form priority=1000 \
  --form duration_s=5 \
  --form resolution=768p \
  --form aspect_ratio=16:9 \
  --form seed=1 \
  --form watermark=false \
  --form reference_video.items='@example-file' \
  --form reference_image.items='@example-file'

import requests

url = "https://apis.viggle.ai/v1/videos"

files = {
    "first_frame_image": ("example-file", open("example-file", "rb")),
    "last_frame_image": ("example-file", open("example-file", "rb")),
    "reference_video.items": ("example-file", open("example-file", "rb")),
    "reference_image.items": ("example-file", open("example-file", "rb"))
}
payload = {
    "prompt": "A paper airplane gliding through a sunlit office",
    "quality": "low",
    "first_frame_image_url": "<string>",
    "last_frame_image_url": "<string>",
    "reference_video": "<string>",
    "reference_video_url": "<string>",
    "reference_image": "<string>",
    "reference_image_url": "<string>",
    "driving_video_url": "<string>",
    "character_image_url": "<string>",
    "character_image_urls": "<string>",
    "priority": "1000",
    "duration_s": "5",
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "seed": "1",
    "watermark": "false"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('prompt', 'A paper airplane gliding through a sunlit office');
form.append('quality', 'low');
form.append('first_frame_image', '<string>');
form.append('first_frame_image_url', '<string>');
form.append('last_frame_image', '<string>');
form.append('last_frame_image_url', '<string>');
form.append('reference_video', '<string>');
form.append('reference_video_url', '<string>');
form.append('reference_image', '<string>');
form.append('reference_image_url', '<string>');
form.append('driving_video_url', '<string>');
form.append('character_image_url', '<string>');
form.append('character_image_urls', '<string>');
form.append('priority', '1000');
form.append('duration_s', '5');
form.append('resolution', '768p');
form.append('aspect_ratio', '16:9');
form.append('seed', '1');
form.append('watermark', 'false');
form.append('reference_video.items', '{
  "fileName": "example-file"
}');
form.append('reference_image.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://apis.viggle.ai/v1/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apis.viggle.ai/v1/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apis.viggle.ai/v1/videos"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apis.viggle.ai/v1/videos")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apis.viggle.ai/v1/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "queued",
  "progress": 50,
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

POST

videos

Generate a video from text, from a first and optional last frame, from a reference video/image, or from a character image and/or driving video

curl --request POST \
  --url https://apis.viggle.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=A paper airplane gliding through a sunlit office' \
  --form quality=low \
  --form first_frame_image='@example-file' \
  --form 'first_frame_image_url=<string>' \
  --form last_frame_image='@example-file' \
  --form 'last_frame_image_url=<string>' \
  --form 'reference_video=<string>' \
  --form 'reference_video_url=<string>' \
  --form 'reference_image=<string>' \
  --form 'reference_image_url=<string>' \
  --form 'driving_video_url=<string>' \
  --form 'character_image_url=<string>' \
  --form 'character_image_urls=<string>' \
  --form priority=1000 \
  --form duration_s=5 \
  --form resolution=768p \
  --form aspect_ratio=16:9 \
  --form seed=1 \
  --form watermark=false \
  --form reference_video.items='@example-file' \
  --form reference_image.items='@example-file'

import requests

url = "https://apis.viggle.ai/v1/videos"

files = {
    "first_frame_image": ("example-file", open("example-file", "rb")),
    "last_frame_image": ("example-file", open("example-file", "rb")),
    "reference_video.items": ("example-file", open("example-file", "rb")),
    "reference_image.items": ("example-file", open("example-file", "rb"))
}
payload = {
    "prompt": "A paper airplane gliding through a sunlit office",
    "quality": "low",
    "first_frame_image_url": "<string>",
    "last_frame_image_url": "<string>",
    "reference_video": "<string>",
    "reference_video_url": "<string>",
    "reference_image": "<string>",
    "reference_image_url": "<string>",
    "driving_video_url": "<string>",
    "character_image_url": "<string>",
    "character_image_urls": "<string>",
    "priority": "1000",
    "duration_s": "5",
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "seed": "1",
    "watermark": "false"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('prompt', 'A paper airplane gliding through a sunlit office');
form.append('quality', 'low');
form.append('first_frame_image', '<string>');
form.append('first_frame_image_url', '<string>');
form.append('last_frame_image', '<string>');
form.append('last_frame_image_url', '<string>');
form.append('reference_video', '<string>');
form.append('reference_video_url', '<string>');
form.append('reference_image', '<string>');
form.append('reference_image_url', '<string>');
form.append('driving_video_url', '<string>');
form.append('character_image_url', '<string>');
form.append('character_image_urls', '<string>');
form.append('priority', '1000');
form.append('duration_s', '5');
form.append('resolution', '768p');
form.append('aspect_ratio', '16:9');
form.append('seed', '1');
form.append('watermark', 'false');
form.append('reference_video.items', '{
  "fileName": "example-file"
}');
form.append('reference_image.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://apis.viggle.ai/v1/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apis.viggle.ai/v1/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apis.viggle.ai/v1/videos"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apis.viggle.ai/v1/videos")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apis.viggle.ai/v1/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA paper airplane gliding through a sunlit office\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\nlow\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"first_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"last_frame_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"driving_video_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"character_image_urls\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"priority\"\r\n\r\n1000\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration_s\"\r\n\r\n5\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n768p\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n16:9\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"watermark\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_video.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"reference_image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "queued",
  "progress": 50,
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "details": {},
    "remediation": {
      "action": "<string>",
      "retry_after_ms": 1
    }
  }
}

Send multipart/form-data — or a plain application/json body — with at least one of character_image_url or character_image_urls, optionally alongside driving_video_url. Supplying any of these three fields is what selects this mode of POST /v1/videos — character-animation generation — and dispatches to a separate backend (viggle-animate) from the other four modes on this endpoint.

Unlike every other POST /v1/videos mode, character-animation mode takes no file uploads at all — driving_video_url and every character image must already be reachable at a URL (https://, or an internal gs:// object) rather than attached to the request. It’s also the only mode that accepts a plain JSON body as an alternative to multipart/form-data; see JSON request body below.

This uses the same POST /v1/videos endpoint as Generate Video (from Text), Generate Video (from First Frame and/or Text), Generate Video (from First-Last Frames and/or Text), and Generate Video (from Reference Video/Image) — which mode runs is selected by which fields you send, not by a separate parameter. Character-animation fields cannot be combined with quality or any frame/reference field from the other four modes; doing so answers 400 INVALID_REQUEST with “driving_video_url/character_image_url cannot be combined with quality”.

Character-animation mode is billed differently from the other four modes: a flat 11 credits ($0.11) per request, regardless of the actual output duration — not ⌈duration_s⌉ × a per-second rate. There’s no quality, duration_s, resolution, aspect_ratio, or seed for this mode. See Pricing below.

Request parameters

Send multipart/form-data, or JSON (see below).

Parameter	Type	Required	Default	Description
`driving_video_url`	string (URI)	No	—	URL of a driving video whose motion is applied to the character image(s). `https://` or internal `gs://`. Single-valued. Must be 5–10 seconds long (inclusive), at least 64x64, and even width/height.
`character_image_url`	string (URI), repeatable	See below	—	Character reference image URL. Can be repeated. Mutually exclusive with `character_image_urls` — supply one field or the other.
`character_image_urls`	array of string (URI)	See below	—	Same as `character_image_url`, as one field instead of repeated ones: a JSON array of strings on a multipart request, or a native array on a JSON request body. Mutually exclusive with `character_image_url`.
`prompt`	string	No	—	Optional style/content guidance. Unlike every other mode, not required and not enforced non-empty.
`watermark`	boolean	No	`false`	Whether to burn in a Viggle watermark. Same field and convention as the other four modes.
`priority`	integer	No	`1000`	Admission-queue priority tier, shared with H3 modes. Must be one of the server’s configured tiers (currently `1000` or `0`); an unsupported value answers `400 INVALID_REQUEST` — “unsupported priority”. Most callers never need to set this.

Supplying driving_video_url and/or character_image_url/character_image_urls is what selects this mode — there’s no separate source parameter. At least one character image is required across character_image_url/character_image_urls; supplying neither is not character-animation mode at all — see Generate Video (from Text) and the other modes for what runs instead.

Driving video vs. character images

Driving video (driving_video_url): optional — a character-animation request can run on character images alone, with no driving video. When supplied, it must be 5–10 seconds long (inclusive) — a narrower window than the 0.5–600 seconds enforced on every other video input in this API — and at least 64x64 with even width and height. A URL that fails to fetch answers 400 INVALID_REQUEST — “failed to fetch driving_video_url”.
Character images (character_image_url / character_image_urls): at least one is required. Up to 4 total are accepted when no driving video is supplied — but only 1 when driving_video_url is present, since the driving video already establishes the motion. Supplying more than that cap answers 400 INVALID_REQUEST — “at most 4 character images are allowed” (or “only one character_image_url is allowed when driving_video_url is provided” specifically for the video+image combination). Supplying both character_image_url and character_image_urls in the same request answers 400 INVALID_REQUEST — “supply only one of character_image_url or character_image_urls”.

Every URL — driving video or character image — must be https:// or gs://; anything else (a bare http://, for example) answers 400 INVALID_REQUEST with “each character_image_url must be a gs:// or https:// URI” (or the driving_video_url equivalent).

JSON request body

Character-animation mode alone also accepts a plain JSON body (Content-Type: application/json) as an alternative to multipart/form-data, native arrays included — useful since this mode never takes file uploads in the first place:

{
  "driving_video_url": "https://example.test/driving.mp4",
  "character_image_urls": ["https://example.test/char1.png", "https://example.test/char2.png"],
  "prompt": "keep the same outfit and background",
  "watermark": false
}

The request body must be a single JSON object containing at least one of driving_video_url, character_image_url, or character_image_urls; an empty or malformed body answers 400 INVALID_REQUEST — “request body must be a JSON object” (or “JSON animation requests require character images” when none of the three fields are present). Since JSON object keys can’t repeat, character_image_url can only ever hold one string in a JSON body — use character_image_urls with a native array whenever you need more than one image over JSON.

Response parameters

Returns 200 OK — an acceptance acknowledgment, not the final result.

Field	Type	Always present	Description
`id`	string	Yes	Public video ID, `anim_`-prefixed.
`status`	string	Yes	Always `queued` on acceptance.
`progress`	integer or null	Yes	Always `null` on acceptance.
`created_at`	string	Yes	ISO 8601 creation timestamp, second precision.

{
  "id": "anim_7c1e4b",
  "status": "queued",
  "progress": null,
  "created_at": "2026-09-09T09:12:03Z"
}

This response deliberately carries none of the fields GET /v1/videos/{video_id} returns (video_url, completed_at, error). See Get Video for the full shape once the video is processing or done — character-animation’s response there carries no seed (H3-only) alongside the fields every video shares.

Pricing

Character-animation mode is billed at a flat rate, unlike every other mode on this endpoint: 11 credits ($0.11) per accepted request, charged at creation time regardless of the actual output duration. This is because the real output duration isn’t known until after the driving video is measured server-side — well after credits must already be reserved — so every request is charged as if it produced the maximum possible output (up to roughly 10 seconds). watermark does not affect price. See Pricing and retention.

Examples

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F driving_video_url=https://example.test/driving.mp4 \
  -F character_image_url=https://example.test/char1.png

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="keep the same outfit and background" \
  -F character_image_url=https://example.test/char1.png \
  -F character_image_url=https://example.test/char2.png

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "driving_video_url": "https://example.test/driving.mp4",
        "character_image_urls": ["https://example.test/char1.png"]
      }'

import os, requests
response = requests.post(
    "https://apis.viggle.ai/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}", "Content-Type": "application/json"},
    json={
        "driving_video_url": "https://example.test/driving.mp4",
        "character_image_urls": ["https://example.test/char1.png"],
    },
)
response.raise_for_status()
video = response.json()

const response = await fetch("https://apis.viggle.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIGGLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    driving_video_url: "https://example.test/driving.mp4",
    character_image_urls: ["https://example.test/char1.png"],
  }),
});
const video = await response.json();

Common errors

Error	Cause
`400 INVALID_REQUEST` — “character images are required”	Neither `character_image_url` nor `character_image_urls` supplied.
`400 INVALID_REQUEST` — “supply only one of character_image_url or character_image_urls”	Both fields supplied together.
`400 INVALID_REQUEST` — “at most 4 character images are allowed”	More than 4 character images supplied across both fields.
`400 INVALID_REQUEST` — “only one character_image_url is allowed when driving_video_url is provided”	More than 1 character image supplied alongside a driving video.
`400 INVALID_REQUEST` — “each character_image_url must be a gs:// or https:// URI” (or “…character_image_urls…”, matching whichever field you used)	A character image used an unsupported URI scheme (not `https://` or `gs://`).
`400 INVALID_REQUEST` — “driving_video_url must be a gs:// or https:// URI”	`driving_video_url` used an unsupported URI scheme.
`400 INVALID_REQUEST` — “driving_video_url must be a single URL”	`driving_video_url` supplied more than once.
`400 INVALID_REQUEST` — “failed to fetch driving_video_url”	The driving video URL couldn’t be fetched.
`400 INVALID_REQUEST` — “driving_video_url duration must be between 5 and 10 seconds (inclusive)“	The fetched driving video was outside the 5–10 second window.
`400 INVALID_REQUEST` — “driving_video_url/character_image_url cannot be combined with quality”	`quality` (or another H3-mode field) supplied alongside a character-animation field.
`400 INVALID_REQUEST` — “unsupported priority”	`priority` set to a value outside the server’s configured tiers.

Next step

Use Get Video with the returned id to poll for the result.

Generate Video (from Text)

Generate from a prompt alone, with no frame image or reference.

Generate Video (from Reference Video/Image)

Carry a subject or style from a reference video and/or up to 4 images, on the H3 backend instead.

Authorizations

Authorization

string

header

required

Server-side SDK clients use a project API key. Remote MCP clients use an OAuth access token. Never expose a project API key in browser code.

Headers

X-Request-Id

string

Optional caller-supplied correlation ID, up to 128 characters. The service returns the effective value in the response header for tracing and support.

Required string length: 1 - 128

X-Viggle-Source

string

Optional source-channel label, up to 128 characters, used to attribute traffic to an SDK, integration, product surface, or internal workflow.

Required string length: 1 - 128

Body

multipart/form-data

Body of POST /v1/videos, multipart/form-data only (character- animation mode below also accepts a plain application/json body — see Generate Video (from Character Animation)). Which fields are supplied selects the generation mode:

Neither first_frame_image/first_frame_image_url nor last_frame_image/last_frame_image_url nor any reference or character-animation field supplied: text-to-video.
A first frame supplied, no last frame: first-frame-to-video.
Both a first frame and a last frame supplied: first+last-frame-to-video.
Any of reference_video/reference_video_url/ reference_image/reference_image_url supplied: reference-video (omni-reference) generation.
driving_video_url and/or character_image_url/ character_image_urls supplied: character-animation generation, dispatched to a separate backend from the four modes above. It has no quality tier, no duration_s/resolution/ aspect_ratio/seed, and prompt is optional rather than required; see below and Generate Video (from Character Animation) for its own fields, pricing, and constraints.

Within a frame slot, supply at most one of the file and the URL form. Supplying both first_frame_image and first_frame_image_url (or both last_frame_image and last_frame_image_url) answers 400 INVALID_REQUEST with "supply only one of first_frame_image or first_frame_image_url" (or the last_frame_* equivalent). A last frame requires a first frame; supplying a last frame with no first frame answers 400 INVALID_REQUEST with "a last frame requires a first frame".

Reference-video mode is selected purely by whether any of the four reference fields is present — there is no separate source/mode parameter, and no error if you meant to but forgot: supplying none of reference_video/reference_video_url/reference_image/ reference_image_url simply generates text-to-video instead (the first bullet above), the same way omitting first_frame_image/ last_frame_image falls back to text-to-video rather than erroring. reference_video and reference_video_url are declared as arrays for forward compatibility, but at most 1 reference video is accepted today; supplying any combination of the two fields that adds up to more than 1 (two files, two URLs, or one of each) answers 400 INVALID_REQUEST with "at most 1 reference video(s) allowed". reference_image and reference_image_url may be mixed freely, but their combined count cannot exceed 4; going over answers 400 INVALID_REQUEST with "at most 4 reference images are allowed". Reference fields cannot be combined with first_frame_image/last_frame_image (file or URL form); doing so answers 400 INVALID_REQUEST with "reference_video/reference_image cannot be combined with first_frame_image/last_frame_image". The reference video itself (independent of duration_s, the target duration of the generated video) must be 0.5–600 seconds long and at least 64x64 with even width and height, the same constraints enforced on uploaded video elsewhere in this API.

Character-animation mode cannot be combined with quality (or any frame/reference field above) — doing so answers 400 INVALID_REQUEST with "driving_video_url/character_image_url cannot be combined with quality". At least one character image is required (character_image_url and character_image_urls are mutually exclusive ways to supply them — "supply only one of character_image_url or character_image_urls" otherwise); up to 4 are accepted when driving_video_url is absent, but only 1 when it's present ("only one character_image_url is allowed when driving_video_url is provided"). driving_video_url itself is optional, single-valued, and — unlike every other video input in this API — checked against a narrower 5–10 second (inclusive) duration window rather than 0.5–600 seconds, on top of the same at-least-64x64/even-dimensions checks.

Billed at ⌈duration_s⌉ × the per-second credit rate for quality (currently 1 credit/second — $0.01/sec — for both low and high). resolution and aspect_ratio do not affect price, and image/video-conditioned generation (first-frame, first-last-frame, or reference-video) costs the same as text-only for the same quality and duration. Character-animation mode is billed differently — a flat rate regardless of actual output duration; see Generate Video (from Character Animation).

Every generated video includes native audio; there is no separate audio flag or field.

prompt

string

Text description of the desired video. Required and non-empty for text, first-frame, first+last-frame, and reference-video modes. Optional (and merely a style/content hint, not enforced non-empty) for character-animation mode.

Minimum string length: 1

Example:

"A paper airplane gliding through a sunlit office"

quality

enum<string>

Generation quality tier — also selects the per-second credit rate charged for this request. low generates faster, for quicker iteration; high generates slower but produces higher-fidelity output. Both tiers are billed at the same $0.01/sec rate. Required for every mode except character-animation, which has no quality tiers and rejects this field outright if supplied.

Available options:

low,

high

Example:

"low"

first_frame_image

file

First-frame image uploaded directly. Mutually exclusive with first_frame_image_url. Supplying either switches on first-frame-to-video mode. Cannot be combined with any reference_video/reference_image field.

first_frame_image_url

string<uri>

Publicly reachable URL of the first-frame image; the service fetches and re-hosts it. Mutually exclusive with first_frame_image. Cannot be combined with any reference_video/reference_image field.

last_frame_image

file

Last-frame image uploaded directly. Mutually exclusive with last_frame_image_url. Valid only alongside a first frame. Cannot be combined with any reference_video/reference_image field.

last_frame_image_url

string<uri>

Publicly reachable URL of the last-frame image; the service fetches and re-hosts it. Mutually exclusive with last_frame_image. Valid only alongside a first frame. Cannot be combined with any reference_video/reference_image field.

reference_video

file[]

Reference video uploaded directly, for reference-video (omni-reference) generation. Declared as an array for forward compatibility, but at most 1 is accepted today — combined with reference_video_url. Not required if at least one reference image is supplied instead. Must be 0.5–600 seconds long and at least 64x64 with even width/height. Cannot be combined with first_frame_image/last_frame_image.

Maximum array length: 1

reference_video_url

string<uri>[]

Publicly reachable URL of the reference video; the service fetches and re-hosts it. Declared as an array for forward compatibility, but at most 1 is accepted today — combined with reference_video. Same duration/resolution constraints as reference_video.

Maximum array length: 1

reference_image

file[]

Reference images uploaded directly, for reference-video (omni-reference) generation. Up to 4 total, combined with reference_image_url. Can be freely mixed with reference_image_url.

Maximum array length: 4

reference_image_url

string<uri>[]

Publicly reachable URLs of reference images; the service fetches and re-hosts each one. Up to 4 total, combined with reference_image. Can be freely mixed with reference_image.

Maximum array length: 4

driving_video_url

string<uri>

Publicly reachable URL (https://) or internal gs:// object of a driving video, for character-animation generation — its motion is applied to the character image(s). Optional and single-valued; a character-animation request can run on character images alone. Must be 5–10 seconds long (inclusive), at least 64x64, and even width/height. Selects character-animation mode together with any character_image_url/character_image_urls; cannot be combined with quality or any frame/reference field above.

character_image_url

string<uri>[]

Character reference image URL(s) (https:// or gs://), repeatable, for character-animation generation. Mutually exclusive with character_image_urls — supply one field or the other, not both. At least one character image is required across the two fields; up to 4 total when driving_video_url is absent, but only 1 when it's present.

character_image_urls

string<uri>[]

Same as character_image_url, supplied as one field instead of repeated ones — as a JSON array of strings on a multipart request, or natively on a JSON request body. Mutually exclusive with character_image_url.

priority

integer

default:1000

Admission-queue priority tier, shared by H3 and character-animation modes. Defaults to 1000 (top tier) — most callers never need to set this. Must be one of the server's configured tiers (currently 1000 or 0); an unsupported value answers 400 INVALID_REQUEST with "unsupported priority".

duration_s

number

default:5

Target video duration in seconds.

Required range: 3 <= x <= 15

resolution

enum<string>

default:768p

Output resolution tier.

Available options:

480p,

768p,

1080p

aspect_ratio

enum<string>

default:16:9

Output aspect ratio.

Available options:

16:9,

9:16,

1:1,

4:3,

3:4,

21:9

seed

integer

Deterministic generation seed. Omit for a random seed. H3 modes only — not applicable to character-animation mode.

Required range: x >= 0

watermark

boolean

default:false

Whether to burn in a Viggle watermark.

Response

Video generation accepted and queued.

Acceptance acknowledgment for POST /v1/videos, shared by all five generation modes. This is a queued confirmation, not the final result — poll GET /v1/videos/{video_id} (or watch it via GET /v1/videos) until status reaches ready, then read video_url from that response.

string

required

Public video ID — vid_-prefixed for the four H3 modes, anim_-prefixed for character-animation mode.

Minimum string length: 1

status

enum<string>

required

Lifecycle state at acceptance time; always queued.

Available options:

queued,

processing,

ready,

failed,

cancelled

progress

integer | null

required

Always null on acceptance.

Required range: 0 <= x <= 100

created_at

string<date-time> | null

required

ISO 8601 creation timestamp, second precision.

Account

Characters

Motions

Video

Generate Video (from Character Animation)

Request parameters

Driving video vs. character images

JSON request body

Response parameters

Pricing

Examples

Common errors

Next step

Generate Video (from Text)

Generate Video (from Reference Video/Image)

Authorizations

Headers

Body

Response

​Request parameters

​Driving video vs. character images

​JSON request body

​Response parameters

​Pricing

​Examples

​Common errors

​Next step

Generate Video (from Text)

Generate Video (from Reference Video/Image)

Authorizations

Headers

Body

Response

Request parameters

Driving video vs. character images

JSON request body

Response parameters

Pricing

Examples

Common errors

Next step