AI Video Generation

POST /v1/ai/video

Generate short video clips from text prompts using Runway Gen-4 models. Create motion graphics, product showcases, abstract backgrounds, and more.

Models

Model	Speed	Quality	Cost	Duration
runway-gen4-turbo	Fast (30-60s)	Good	$0.55	5-10s
runway-gen4-hq	Slow (2-5min)	Highest	$1.10	5-10s

Request

Field	Type	Required	Description
prompt	string	Yes	Text description of the desired video
model	string	No	runway-gen4-turbo, runway-gen4-hq (default: runway-gen4-turbo)
duration	number	No	Duration in seconds: 5 or 10 (default: 5)
aspect_ratio	string	No	16:9, 9:16, 1:1 (default: 16:9)
image_url	string	No	Reference image to guide generation (image-to-video)
callback	string	No	Webhook URL

Text-to-Video

curl

curl -X POST https://api.vidiking.com/v1/ai/video \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Aerial drone shot flying over a lush green forest with morning mist, cinematic, smooth camera movement",
    "model": "runway-gen4-turbo",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Node.js

const result = await client.ai.generateVideo({
  prompt: 'Aerial drone shot flying over a lush green forest with morning mist, cinematic',
  model: 'runway-gen4-turbo',
  duration: 5,
  aspectRatio: '16:9',
});

// Poll for completion (video generation takes 30s-5min)
const job = await client.pollJob(result.jobId);
console.log('Video URL:', job.url);

Python

result = client.ai.generate_video(
    prompt="Aerial drone shot flying over a lush green forest with morning mist, cinematic",
    model="runway-gen4-turbo",
    duration=5,
    aspect_ratio="16:9",
)

# Poll for completion
job = client.poll_job(result.job_id)
print("Video URL:", job.url)

Image-to-Video

Provide a reference image to guide the video generation. The output will animate from the provided image.

curl -X POST https://api.vidiking.com/v1/ai/video \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Gentle camera push-in, the subject turns and smiles, soft bokeh background",
    "model": "runway-gen4-hq",
    "duration": 5,
    "image_url": "https://example.com/portrait.jpg"
  }'

Response

{
  "id": "job_vid_abc123",
  "status": "QUEUED",
  "created_at": "2025-01-15T10:30:00Z"
}

When complete:

{
  "id": "job_vid_abc123",
  "status": "COMPLETE",
  "url": "https://cdn.vidiking.com/ai/job_vid_abc123.mp4",
  "duration": 5,
  "model": "runway-gen4-turbo",
  "credits_used": 40,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:45Z"
}

Prompt Tips

Good prompts produce better results. Here are some tips:

Be specific about camera movement:

• "Slow dolly forward through a corridor"
• "Aerial drone shot circling a building"
• "Static wide shot with subtle parallax"

Describe lighting and mood:

• "Golden hour sunlight casting long shadows"
• "Moody neon-lit cyberpunk alley at night"
• "Bright, clean studio lighting on white background"

Specify style:

• "Cinematic, shallow depth of field, 4K"
• "Timelapse of clouds moving across a skyline"
• "Slow motion water droplets on glass"

Avoid:

• Text or specific words in the video (AI video models struggle with text)
• Rapid scene changes (keep it to one continuous shot)
• Specific people or copyrighted characters

Using Generated Video in Timelines

// Generate a background video
const bg = await client.ai.generateVideo({
  prompt: 'Abstract flowing particles in blue and purple, seamless loop',
  duration: 10,
});
const bgJob = await client.pollJob(bg.jobId);

// Use in a composition
const { jobId } = await client.render({
  timeline: {
    tracks: [
      {
        clips: [
          {
            asset: { type: 'title', text: 'AI-Powered', style: 'future', size: 'large' },
            start: 1,
            length: 8,
            transition: { in: 'fade', out: 'fade' },
          },
        ],
      },
      {
        clips: [
          {
            asset: { type: 'video', src: bgJob.url },
            start: 0,
            length: 10,
          },
        ],
      },
    ],
  },
  output: { format: 'mp4', resolution: 'hd' },
});

Quality Comparison

	Turbo	HQ
Generation time	30-60 seconds	2-5 minutes
Motion quality	Good, occasional artifacts	Smooth, consistent
Detail	Good	Excellent
Best for	Prototyping, backgrounds	Final output, hero content
Cost	$0.55	$1.10