Videos

Generate videos.

Visit Voidstone.ai to try our video generation interface.

AUTH Authentication
All API requests require authentication using an API key. Include your API key in the X-API-Key header with every request.
Authentication header
X-API-Key: your-api-key-here
Example request with authentication
curl https://api.voidstone.ai/v1/videos \\
  -H "X-API-Key: your-api-key-here" \\
  -F "video=@input.mp4" \\
  -F "prompt=A calico cat playing a piano on stage" \\
  -F "character_ref=@cat.jpg"
Error responses
If you don't provide an API key or provide an invalid key, you'll receive one of these errors: 
// Missing API key
{
  "detail": "API key required. Please provide X-API-Key header."
}

// Invalid API key
{
  "detail": "Invalid API key."
}
POST /v1/videos
Create a video
Request body parameters
Name Type Description
video Required file Video file upload (or use video_url)
video_url Optional string URL to video file (alternative to file upload)
prompt Required string Text prompt that describes the video to generate.
character_ref Required file Character reference image file (or use character_ref_url)
character_ref_url Optional string URL to character reference image
use_static_background Optional boolean Whether to use static background mode (default: false)
background_image Optional file Background image file (required if use_static_background=true)
background_image_url Optional string URL to background image
Example request
curl https://api.voidstone.ai/v1/videos \\
  -H "X-API-Key: your-api-key-here" \\
  -F "video=@input.mp4" \\
  -F "prompt=A calico cat playing a piano on stage" \\
  -F "character_ref=@cat.jpg"
Response
{
  "id": "video_abc123...",
  "object": "video",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "message": "Video generation job created"
}
GET /v1/videos/{video_id}
Get the status of a video generation job.
Path parameters
Name Type Description
video_id Required string Job ID (format: video_<hex>)
Example request
curl https://api.voidstone.ai/v1/videos/video_abc123... \\
  -H "X-API-Key: your-api-key-here"
Response
{
  "id": "video_abc123...",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712698000,
  "output_video_path": "/path/to/output.mp4",
  "download_url": "/v1/videos/video_abc123.../download"
}
GET /v1/videos/{video_id}/download
Download the generated video file.
Example request
curl -O https://api.voidstone.ai/v1/videos/video_abc123.../download \\
  -H "X-API-Key: your-api-key-here"
GET /health
Health check endpoint.
Response
{
  "status": "healthy"
}

Job statuses

Error responses

When a job fails, the error field contains: 
{
  "id": "video_abc123...",
  "status": "failed",
  "error": {
    "message": "Video file is invalid or cannot be processed",
    "type": "validation_error",
    "code": "invalid_video_file",
    "details": "The uploaded video file is corrupted, invalid, or cannot be processed by ffmpeg"
  }
}