Skip to main content
POST /v1/videos
Creates a video generation task from a text prompt. Video generation is asynchronous - this endpoint returns a video ID that can be used to check the status and download the result.
Video generation can take several minutes depending on the model and parameters. Use the Get Video endpoint to check the status.

​
Request Body

This endpoint accepts multipart/form-data.
​
model
string
required
The video generation model to use (e.g., sora-2).
​
prompt
string
required
A text description of the video to generate.
​
size
string
The dimensions of the output video (e.g., 1920x1080, 1080x1920, 1280x720).
​
seconds
string
The duration of the video in seconds.
​
input_reference
file
An optional reference image or video to guide generation.

​
Response

​
id
string
Unique identifier for the video generation task.
​
status
string
The current status of the video generation. Possible values: pending, processing, completed, failed.
​
created_at
integer
Unix timestamp of when the task was created.

​
Examples

​
Basic Video Generation

import requests

url = "https://api.voidai.app/v1/videos"
headers = {
    "Authorization": "Bearer sk-voidai-your_key_here"
}
data = {
    "model": "sora-2",
    "prompt": "A serene beach at sunset with gentle waves",
    "size": "1920x1080",
    "seconds": "10"
}

response = requests.post(url, headers=headers, data=data)
video = response.json()

print(f"Video ID: {video['id']}")
print(f"Status: {video['status']}")

​
With Reference Image

import requests

url = "https://api.voidai.app/v1/videos"
headers = {
    "Authorization": "Bearer sk-voidai-your_key_here"
}
data = {
    "model": "sora-2",
    "prompt": "Animate this scene with flowing water and moving clouds",
    "size": "1920x1080",
    "seconds": "5"
}
files = {
    "input_reference": open("reference.jpg", "rb")
}

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

​
Response Example

{
  "id": "vid_abc123def456",
  "status": "pending",
  "created_at": 1701691200
}

​
Workflow

  1. Create Video - Submit your prompt and receive a video ID
  2. Poll Status - Use Get Video to check when processing completes
  3. Download - Use Download Video to retrieve the final video
import time
import requests

# 1. Create video
response = requests.post(
    "https://api.voidai.app/v1/videos",
    headers={"Authorization": "Bearer sk-voidai-your_key_here"},
    data={"model": "sora-2", "prompt": "A cat playing piano"}
)
video_id = response.json()["id"]

# 2. Poll for completion
while True:
    status_response = requests.get(
        f"https://api.voidai.app/v1/videos/{video_id}",
        headers={"Authorization": "Bearer sk-voidai-your_key_here"}
    )
    status = status_response.json()["status"]

    if status == "completed":
        break
    elif status == "failed":
        raise Exception("Video generation failed")

    time.sleep(10)  # Check every 10 seconds

# 3. Download video
video_response = requests.get(
    f"https://api.voidai.app/v1/videos/{video_id}/content",
    headers={"Authorization": "Bearer sk-voidai-your_key_here"}
)

with open("output.mp4", "wb") as f:
    f.write(video_response.content)