Generate AI Video

curl --request POST \
  --url https://whollyapi.com/api/v1/runway/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "imageUrl": "<string>",
  "duration": 123,
  "quality": "<string>",
  "aspectRatio": "<string>",
  "waterMark": "<string>"
}
'

import requests

url = "https://whollyapi.com/api/v1/runway/generate"

payload = {
    "prompt": "<string>",
    "imageUrl": "<string>",
    "duration": 123,
    "quality": "<string>",
    "aspectRatio": "<string>",
    "waterMark": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    imageUrl: '<string>',
    duration: 123,
    quality: '<string>',
    aspectRatio: '<string>',
    waterMark: '<string>'
  })
};

fetch('https://whollyapi.com/api/v1/runway/generate', 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://whollyapi.com/api/v1/runway/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'imageUrl' => '<string>',
    'duration' => 123,
    'quality' => '<string>',
    'aspectRatio' => '<string>',
    'waterMark' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://whollyapi.com/api/v1/runway/generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://whollyapi.com/api/v1/runway/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://whollyapi.com/api/v1/runway/generate")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}"

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

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "taskId": "<string>"
  }
}

POST

api

runway

generate

Generate AI Video

curl --request POST \
  --url https://whollyapi.com/api/v1/runway/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "imageUrl": "<string>",
  "duration": 123,
  "quality": "<string>",
  "aspectRatio": "<string>",
  "waterMark": "<string>"
}
'

import requests

url = "https://whollyapi.com/api/v1/runway/generate"

payload = {
    "prompt": "<string>",
    "imageUrl": "<string>",
    "duration": 123,
    "quality": "<string>",
    "aspectRatio": "<string>",
    "waterMark": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    imageUrl: '<string>',
    duration: 123,
    quality: '<string>',
    aspectRatio: '<string>',
    waterMark: '<string>'
  })
};

fetch('https://whollyapi.com/api/v1/runway/generate', 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://whollyapi.com/api/v1/runway/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'imageUrl' => '<string>',
    'duration' => 123,
    'quality' => '<string>',
    'aspectRatio' => '<string>',
    'waterMark' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://whollyapi.com/api/v1/runway/generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://whollyapi.com/api/v1/runway/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://whollyapi.com/api/v1/runway/generate")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"duration\": 123,\n  \"quality\": \"<string>\",\n  \"aspectRatio\": \"<string>\",\n  \"waterMark\": \"<string>\"\n}"

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

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "taskId": "<string>"
  }
}

Create dynamic AI-generated videos from text prompts or image references.

Create a Video Generation Task

POST /api/v1/runway/generate

Authentication

All API requests require a Bearer Token.

Authorization: Bearer YOUR_API_KEY

Usage Guide

Create short AI videos of 5–10 seconds.
Generate videos from text descriptions or reference images.
Suitable for social media content, digital art, and concept visualization.

Parameters

Prompt

string

required

Use prompt to be specific about the subject, action, style, and setting. With an image, describe how to animate or modify the image..Maximum length: 1,800 characters.

Image Reference

string

imageUrl is optional. When supplied, the AI creates a video by animating or extending the referenced image.When imageUrl is provided, aspectRatio is invalid and the final aspect ratio is determined by the image.

Duration

number

required

Generated video duration in seconds.Supported values:

5
10

Note: 10-second videos do not support 1080p resolution.
Default: 5

Quality

string

required

Specify the resolution of the output video.Supported output resolutions:

720p
1080p

Note: 10-second videos do not support 1080p resolution.
Default: 720p

Aspect Ratio

string

Applies to multi-image generation. In single-image mode, video dimensions follow the source image dimensions.Supported values: 3:4, 4:3, 1:1, 16:9, 9:16.For text-only generation, aspectRatio must be explicitly specified.

Watermark

string

Use waterMark controls watermark text in the bottom-right corner.

Empty string: no watermark.
Non-empty string: displays the specified text.

Example: whollyapi.com

Request Example

{
  "prompt": "A fluffy orange cat dancing energetically in a colorful room with disco lights",
  "imageUrl": "https://example.com/cat-image.jpg",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "9:16",
  "waterMark": "kie.ai",
}

Text-to-Video Example

{
  "prompt": "A fluffy orange cat dancing energetically in a colorful room with disco lights",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "9:16",
  "waterMark": "",
}

Image-to-Video Example

{
  "prompt": "Animate the cat dancing energetically while the disco lights flicker around it.",
  "imageUrl": "https://example.com/cat-image.jpg",
  "duration": 5,
  "quality": "720p",
  "waterMark": "kie.ai",
}

Create Task Response

number

Response status code.

string

Response message. Contains the error description when the request fails.Example: success

object

required

The task data object containing task id.

string

required

The unique identifier for this task.Example: ee603959-98c4-debb-bgfgbfg45

Query Task Status

After submitting a task, use the unified query endpoint to check the task progress and retrieve the generated results.

Get Task Details

Check task status, monitor generation progress, and retrieve results.

Error Response

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Developer Notes

Generated videos are stored for 14 days before automatic deletion.
Text-only generation requires aspectRatio.
With imageUrl, the image determines the final aspect ratio.
10-second videos cannot be generated at 1080p.

Response Status Codes

Code	Meaning
`200`	Success — request processed successfully.
`401`	Unauthorized — authentication credentials are missing or invalid.
`404`	Not Found — requested resource or endpoint does not exist.
`422`	Validation Error — request parameters failed validation.
`451`	Failed to fetch the image; verify access limits imposed by the user or service provider.
`455`	Service Unavailable — system is undergoing maintenance.
`500`	Server Error — unexpected error while processing the request.

The source also documents these broader error codes:

Code	Meaning
`402`	Insufficient Credits.
`408`	Upstream service issue; no result returned for over 10 minutes.
`429`	Rate Limited.
`501`	Generation Failed.
`505`	Feature Disabled.

​Create a Video Generation Task

​Authentication

​Usage Guide

​Parameters

​Prompt

​Image Reference

​Duration

​Quality

​Aspect Ratio

​Watermark

​Request Example

​Text-to-Video Example

​Image-to-Video Example

​Create Task Response

​Query Task Status

Get Task Details

​Error Response

​Developer Notes

​Response Status Codes

Create a Video Generation Task

Authentication

Usage Guide

Parameters

Prompt

Image Reference

Duration

Quality

Aspect Ratio

Watermark

Request Example

Text-to-Video Example

Image-to-Video Example

Create Task Response

Query Task Status

Error Response

Developer Notes

Response Status Codes