Generate Video (from Reference Video/Image)

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

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=@example-file \
  --form 'reference_video_url=<string>' \
  --form reference_image=@example-file \
  --form 'reference_image_url=<string>' \
  --form driving_video=@example-file \
  --form 'driving_video_url=<string>' \
  --form character_image=@example-file \
  --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 enhance=true

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": ("example-file", open("example-file", "rb")),
    "reference_image": ("example-file", open("example-file", "rb")),
    "driving_video": ("example-file", open("example-file", "rb")),
    "character_image": ("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_url": "<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",
    "enhance": "true"
}
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', '<string>');
form.append('driving_video_url', '<string>');
form.append('character_image', '<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('enhance', 'true');

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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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 driving video and a character image

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=@example-file \
  --form 'reference_video_url=<string>' \
  --form reference_image=@example-file \
  --form 'reference_image_url=<string>' \
  --form driving_video=@example-file \
  --form 'driving_video_url=<string>' \
  --form character_image=@example-file \
  --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 enhance=true

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": ("example-file", open("example-file", "rb")),
    "reference_image": ("example-file", open("example-file", "rb")),
    "driving_video": ("example-file", open("example-file", "rb")),
    "character_image": ("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_url": "<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",
    "enhance": "true"
}
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', '<string>');
form.append('driving_video_url', '<string>');
form.append('character_image', '<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('enhance', 'true');

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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\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=\"enhance\"\r\n\r\ntrue\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 with at least one of reference_video, reference_video_url, reference_image, or reference_image_url. Supplying any of these four fields is what selects this mode of POST /v1/videos — reference-video (omni-reference) generation — and produces a Viggle-optimized MiniMax H3 video with native audio.

Quick Start: Reference to Video

Upload a reference video and generate your first result with cURL, Node, or Python.

If you supply none of the four reference fields, this is not an error — the request silently falls back to Generate Video (from Text) instead, the same way omitting first_frame_image/last_frame_image there falls back to text-only. There is no source/mode parameter to force reference-video selection independently of these fields, so double-check your request actually includes one of them before relying on this mode.

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 Using Viggle-Animate — which mode runs is selected by which fields you send, not by a separate parameter. Reference fields cannot be combined with first_frame_image/last_frame_image.

Every generated video includes native audio — there’s no separate audio flag or field. Pricing (1 credit =

0.01): ⌈`duration_s`⌉ × the per-second rate for `resolution` — **

0.01/sec (1 credit/second)** at 480p/768p/1080p/2k for both low and high, rising to $0.05/sec (5 credits/second) at 4k. Reference-conditioned generation costs the same as text-only for the same quality, resolution, and duration; aspect_ratio and enhance don’t affect price. See Pricing and retention.

Request parameters

Send multipart/form-data.

Parameter	Type	Required	Default	Description
`prompt`	string	Yes	—	Non-empty text description of the desired video. Still required with reference video/images supplied.
`quality`	string	Yes	—	`low` for faster generation and quicker iteration, or `high` for higher-fidelity output. Both tiers are billed at the same per-second rate for a given `resolution`.
`reference_video`	file	See below	—	Reference video uploaded directly. Declared as a repeatable field for forward compatibility, but at most 1 reference video is accepted today, combined with `reference_video_url`. Not required if at least one reference image is supplied instead.
`reference_video_url`	string (URI)	See below	—	Publicly reachable URL of the reference video; the service fetches and re-hosts it. Declared as a repeatable field for forward compatibility, but at most 1 reference video is accepted today, combined with `reference_video`.
`reference_image`	file, repeatable	See below	—	Reference image uploaded directly. Can be repeated, and freely mixed with `reference_image_url` — combined total across both is capped at 4.
`reference_image_url`	string (URI), repeatable	See below	—	Publicly reachable URL of a reference image; the service fetches and re-hosts it. Can be repeated, and freely mixed with `reference_image` — combined total across both is capped at 4.
`duration_s`	number	No	`5`	Requested video duration in seconds, 5–15 inclusive; defaults to 5. Rounded up to determine the credit charge.
`resolution`	string	No	`768p`	`480p`, `768p`, `1080p`, `2k`, or `4k`. `4k` is billed at $0.05/sec (5 credits/second); the rest are billed at $ 0.01/sec (1 credit/second).
`aspect_ratio`	string	No	`16:9`	`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, or `21:9`. Does not affect price.
`seed`	integer	No	—	≥ 0. Omit for a random seed.
`watermark`	boolean	No	`false`	Whether to burn in a Viggle watermark.
`enhance`	boolean	No	`true`	Whether to run a low-effort AI Planner pass that rewrites `prompt` before generation — the supplied reference video/images are unchanged. Pass `false` to use `prompt` exactly as given. Does not affect price.
`priority`	integer	No	`1000`	Admission-queue priority tier. Must be one of the server’s configured tiers (currently `1000` or `0`). Most callers never need to set this.

Supplying any of reference_video/reference_video_url/reference_image/reference_image_url is what selects this mode — there’s no separate source parameter. Supplying none of the four does not error; see the warning above — the request is generated as text-to-video instead.

Reference video vs. reference images

You can supply a reference video, one or more reference images, or both together in the same request — a reference video is not required if you supply at least one reference image, and vice versa.

Reference video (reference_video / reference_video_url): both fields are declared as arrays for forward compatibility, but at most 1 reference video is accepted today across the two combined — supplying more (two files, two URLs, or one of each) answers 400 INVALID_REQUEST — “at most 1 reference video(s) allowed”. The reference video itself must be at most 100 MiB (uploaded or fetched), contain a readable video stream (MP4, MOV, WebM, etc.), be 0.5–600 seconds long, and be at least 64x64 with even width and height — the same upload constraints enforced elsewhere in this API. An oversized upload answers “reference_video: video exceeds 100 MiB limit”; an oversized URL answers “failed to fetch reference_video_url: media exceeds size limit”, and any other problem with a fetched video answers “reference_video_url is not a valid video”. This is independent of duration_s, which controls the duration of the generated output video, not the reference.
Reference images (reference_image / reference_image_url): each can be repeated and the two forms can be freely mixed, but the combined count across both cannot exceed 4. Going over answers 400 INVALID_REQUEST — “at most 4 reference images are allowed”. Each uploaded image may be up to 20 MiB, and each image fetched from reference_image_url up to 30 MiB. The format is detected from the image bytes — JPEG, PNG, WebP, GIF, BMP, TIFF, or HEIC/HEIF/AVIF — with no minimum or maximum dimensions; an image at or above 4K (long edge ≥ 3840 px or short edge ≥ 2160 px) is downscaled to fit within 1920×1080, keeping its aspect ratio. An image that can’t be decoded answers “reference_image must be a valid image” (upload) or “reference_image_url is not a valid image” (URL).

Reference fields cannot be combined with first_frame_image/last_frame_image (file or URL form). Supplying both answers 400 INVALID_REQUEST — “reference_video/reference_image cannot be combined with first_frame_image/last_frame_image”.

Response parameters

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

Field	Type	Always present	Description
`id`	string	Yes	Public video ID, `vid_`-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": "vid_3f2a9c",
  "status": "queued",
  "progress": null,
  "created_at": "2026-08-24T09:12:03Z"
}

This response deliberately carries none of the fields GET /v1/videos/{video_id} returns (stage, video_url, alpha_url, completed_at, error). See Get Video for the full shape once the video is processing or done.

Examples

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="keep the same outfit and walk forward" \
  -F quality=high \
  -F reference_video=@./reference.mp4 \
  -F reference_image_url=https://example.test/ref1.png \
  -F duration_s=8

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="a dancer in the same style" \
  -F quality=low \
  -F reference_video_url=https://example.test/ref.mp4 \
  -F reference_image_url=https://example.test/img1.png \
  -F reference_image_url=https://example.test/img2.png

curl https://apis.viggle.ai/v1/videos \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F prompt="combine these two references" \
  -F quality=low \
  -F reference_image=@./img1.png \
  -F reference_image=@./img2.png

import os, requests
response = requests.post(
    "https://apis.viggle.ai/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
    data={
        "prompt": "keep the same outfit and walk forward",
        "quality": "high",
        "reference_video_url": "https://example.test/ref.mp4",
        "duration_s": 8,
    },
)
response.raise_for_status()
video = response.json()

const form = new FormData();
form.append("prompt", "a dancer in the same style");
form.append("quality", "low");
form.append("reference_video_url", "https://example.test/ref.mp4");
form.append("reference_image_url", "https://example.test/img1.png");
form.append("reference_image_url", "https://example.test/img2.png");
const response = await fetch("https://apis.viggle.ai/v1/videos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
  body: form,
});
const video = await response.json();

`@viggle/sdk`

const video = await client.videos.create({
  prompt: "keep the same outfit and walk forward",
  quality: "high",
  referenceVideoUrl: "https://example.com/ref.mp4",
  referenceImageUrl: ["https://example.com/img1.png", "https://example.com/img2.png"],
  durationS: 8,
});
// video.id, video.status ("queued", ...); poll with client.videos.get(video.id)

Common errors

Error	Cause
`400 INVALID_REQUEST` — “at most 1 reference video(s) allowed”	`reference_video` and/or `reference_video_url` together supply more than 1 reference video.
`400 INVALID_REQUEST` — “at most 4 reference images are allowed”	`reference_image` and `reference_image_url` together exceed 4 images.
`400 INVALID_REQUEST` — “reference_video/reference_image cannot be combined with first_frame_image/last_frame_image”	A reference field supplied alongside `first_frame_image`/`last_frame_image` (file or URL form).
`400 INVALID_REQUEST` — “enhance must be a boolean”	`enhance` supplied with a value that isn’t parseable as a boolean.
`400 INVALID_REQUEST` — “invalid render request: unsupported priority 500”	`priority` set to an integer outside the server’s configured tiers (currently `1000` or `0`); the message ends with the value you sent (here `500`).
`400 INVALID_REQUEST` — “priority must be an integer”	`priority` isn’t parseable as an integer.

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 First Frame and/or Text)

Anchor only the start of the video, with no last frame.

Generate Video (from First-Last Frames and/or Text)

Also anchor the end of the video on a last frame.

Using Viggle-Animate

Apply a driving video’s motion and/or character images on a separate backend.

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/driving_video_url and/or character_image/ character_image_url/character_image_urls supplied: character-animation generation, dispatched to a separate backend from the four modes above. A driving video is optional. Without one, up to 4 character images are accepted, all references of one character; with one, up to 5 are accepted, each replacing one person in the driving video. 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, and at most 100 MiB whether uploaded or fetched from reference_video_url.

Frame and reference images (first_frame_image, last_frame_image, reference_image) may be up to 20 MiB each when uploaded, and up to 30 MiB when fetched from the matching *_url field. The format is detected from the image bytes — JPEG, PNG, WebP, GIF, BMP, TIFF, or HEIC/HEIF/AVIF — and there is no minimum or maximum dimension; an image at or above 4K (long edge >= 3840 px or short edge >= 2160 px) is downscaled to fit 1920x1080, keeping its aspect ratio. An oversized upload answers 400 INVALID_REQUEST with "invalid or oversized first_frame_image upload" (naming the field), an undecodable one with "first_frame_image must be a valid image"; a URL that can't be decoded answers "first_frame_image_url is not a valid image", and an unreadable reference video URL answers "reference_video_url is not a valid video".

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". A driving video is optional; when supplied, use driving_video (an uploaded file) or driving_video_url, not both. It is checked against a 5–15 second (inclusive) duration window (truncated to whole seconds first, so 15.9s is accepted as 15s), on top of the same at-least-64x64 and even-dimension checks. At least one character image is required, as character_image uploads or values supplied through character_image_url/character_image_urls — uploads and URL fields cannot be combined ("supply character images as uploads or as character_image_url/character_image_urls, not both"), character_image_url/character_image_urls remain mutually exclusive with each other ("supply only one of character_image_url or character_image_urls"). Up to 4 images are accepted without a driving video, and up to 5 with one; going over answers 400 INVALID_REQUEST with "at most 4 character images are allowed" (or "at most 5 ..." with a driving video).

Billed at ⌈duration_s⌉ × the per-second credit rate for resolution (currently 1 credit/second — $0.01/sec — at 480p, 768p, 1080p, and 2k, rising to 5 credits/second — $0.05/sec — at 4k; the same rate applies to both quality tiers). quality, aspect_ratio, and enhance 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, resolution, and duration. Character-animation mode is billed at 1 credit/second instead: with a driving video it reserves the driving video's measured duration rounded up (5–16 credits); without one it reserves a flat 11 credits. On completion the charge is settled against the finished video's duration, never above the reservation. It is not tied to duration_s; 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. low generates faster, for quicker iteration; high generates slower but produces higher-fidelity output. Both tiers are billed at the same per-second rate for a given resolution — see resolution below. 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. Up to 20 MiB; JPEG, PNG, WebP, GIF, BMP, TIFF, or HEIC/HEIF/AVIF, detected from the file contents. An image with a long edge of 3840 px or more, or a short edge of 2160 px or more, is downscaled to fit 1920x1080, keeping its aspect ratio.

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. The fetched image may be up to 30 MiB, in the same formats and with the same downscaling as the upload form.

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. Up to 20 MiB; JPEG, PNG, WebP, GIF, BMP, TIFF, or HEIC/HEIF/AVIF, detected from the file contents. An image with a long edge of 3840 px or more, or a short edge of 2160 px or more, is downscaled to fit 1920x1080, keeping its aspect ratio.

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. The fetched image may be up to 30 MiB, in the same formats and with the same downscaling as the upload form.

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. Up to 100 MiB, in any container with a readable video stream (MP4, MOV, WebM, etc.). 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 size, duration, and 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. Up to 20 MiB; JPEG, PNG, WebP, GIF, BMP, TIFF, or HEIC/HEIF/AVIF, detected from the file contents. An image with a long edge of 3840 px or more, or a short edge of 2160 px or more, is downscaled to fit 1920x1080, keeping its aspect ratio.

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. Each fetched image may be up to 30 MiB, in the same formats and with the same downscaling as reference_image.

Maximum array length: 4

driving_video

file

Optional driving video uploaded directly for character-animation generation. Mutually exclusive with driving_video_url. When present, the request may carry up to 5 character images, each replacing one person in the video; it is validated for 5–15 second duration, at least 64x64, and even dimensions, then staged to object storage.

driving_video_url

string<uri>

Optional https:// driving-video URL for character-animation generation. Mutually exclusive with driving_video. When present, the request may carry up to 5 character images, each replacing one person in the video; it must be 5–15 seconds long, at least 64x64, with even dimensions.

character_image

file[]

Character reference images uploaded directly for character-animation generation. Up to 4 are accepted without a driving video, or 5 when a driving video is present. Mutually exclusive with URL-form character images.

Maximum array length: 5

character_image_url

string<uri>[]

Repeatable character reference image https:// URL. Up to 4 are accepted without a driving video, or 5 when a driving video is present. Mutually exclusive with character_image_urls and uploaded character images.

Maximum array length: 5

character_image_urls

string<uri>[]

Same as character_image_url, supplied as one JSON-array field. Up to 4 are accepted without a driving video, or 5 when a driving video is present. Mutually exclusive with character_image_url and uploaded character images.

Maximum array length: 5

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 integer answers 400 INVALID_REQUEST with "invalid render request: unsupported priority 500" (ending with the value sent) in H3 modes, or "unsupported priority" in character-animation mode; a non-integer answers "priority must be an integer".

duration_s

number

default:5

Requested video duration in seconds, between 5 and 15 inclusive. Defaults to 5.

Required range: 5 <= x <= 15

resolution

enum<string>

default:768p

Output resolution tier — also selects the per-second credit rate charged for this request. 480p, 768p, 1080p, and 2k are billed at $0.01/sec (1 credit/second); 4k is billed at $0.05/sec (5 credits/second).

Available options:

480p,

768p,

1080p,

2k,

4k

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<int64>

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.

enhance

boolean

default:true

Whether to run a low-effort AI Planner pass that rewrites only prompt before generation; any supplied frame or reference video/image is left unchanged. H3 modes only — not applicable to character-animation mode. Defaults to true; pass false to use prompt exactly as given. Does not affect price.

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

Renders

Videos

Viggle Image

Generate Video (from Reference Video/Image)

Quick Start: Reference to Video

Request parameters

Reference video vs. reference images

Response parameters

Examples

`@viggle/sdk`

Common errors

Next step

Generate Video (from Text)

Generate Video (from First Frame and/or Text)

Generate Video (from First-Last Frames and/or Text)

Using Viggle-Animate

Authorizations

Headers

Body

Response

Quick Start: Reference to Video

​Request parameters

​Reference video vs. reference images

​Response parameters

​Examples

​@viggle/sdk

​Common errors

​Next step

Generate Video (from Text)

Generate Video (from First Frame and/or Text)

Generate Video (from First-Last Frames and/or Text)

Using Viggle-Animate

Authorizations

Headers

Body

Response

Request parameters

Reference video vs. reference images

Response parameters

Examples

`@viggle/sdk`

Common errors

Next step