​
Welcome to Runway API

The Runway API enables you to generate high-quality AI videos using the power of Runway’s advanced AI models. Whether you’re building an app, automating workflows, or creating dynamic content, our API provides simple and reliable access to AI video generation.

Text-to-Video

Transform text prompts into dynamic video content

Image-to-Video

Animate existing images into engaging videos

Video Extension

Extend videos to create longer sequences

Task Management

Track and monitor your video generation tasks

​
Authentication

All API requests require authentication using a Bearer token. Get your API key from the API Key Management Page.
Keep your API key secure and never share it publicly. If compromised, reset it immediately.

​
API Base URL

https://api.kie.ai

​
Authentication Header

Authorization: Bearer YOUR_API_KEY

​
Quick Start Guide

​
Step 1: Generate Your First Video

Start with a simple text-to-video generation request: 
curl -X POST "https://api.kie.ai/api/v1/runway/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A fluffy orange cat dancing energetically in a colorful room with disco lights",
    "duration": 5,
    "quality": "720p",
    "aspectRatio": "16:9",
    "waterMark": ""
  }'

​
Step 2: Check Task Status

Use the returned task ID to check the generation status: 
curl -X GET "https://api.kie.ai/api/v1/runway/record-detail?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Format

Successful Response: 
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}
Task Status Response: 
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "state": "success",
    "generateTime": "2023-08-15 14:30:45",
    "videoInfo": {
      "videoId": "485da89c-7fca-4340-8c04-101025b2ae71",
      "videoUrl": "https://file.com/k/xxxxxxx.mp4",
      "imageUrl": "https://file.com/m/xxxxxxxx.png"
    },
    "expireFlag": 0
  }
}

​
Generation Types

Generate videos from text descriptions:
{
  "prompt": "A majestic eagle soaring through mountain clouds at sunset",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "16:9"
}

​
Video Quality Options

Choose the right quality for your needs:

720p HD

Standard qualityBalanced file size and quality, suitable for most applicationsCompatible with both 5-second and 8-second durations

1080p Full HD

Premium qualityHigher resolution for professional contentOnly available for 5-second videos

​
Key Parameters

​
prompt
string
required
Text description of the desired video content. Be specific about actions, movements, and visual style.Tips for better prompts:
  • Describe specific actions and movements (e.g., “walking slowly”, “spinning rapidly”)
  • Include visual style descriptors (e.g., “cinematic”, “animated”, “realistic”)
  • Specify camera angles when relevant (e.g., “close-up”, “wide shot”, “tracking shot”)
  • Add lighting and atmosphere details (e.g., “golden hour lighting”, “dramatic shadows”)
​
duration
number
required
Video duration in seconds. Choose from:
  • 5 - 5-second video (compatible with both 720p and 1080p)
  • 8 - 8-second video (only compatible with 720p)
​
quality
string
required
Video resolution quality:
  • 720p - HD quality, compatible with all durations
  • 1080p - Full HD quality, only available for 5-second videos
​
aspectRatio
string
required
Video aspect ratio. Choose from:
  • 16:9 - Widescreen (recommended for landscape content)
  • 9:16 - Vertical (perfect for mobile and social media)
  • 1:1 - Square (social media posts)
  • 4:3 - Traditional format
  • 3:4 - Portrait orientation
​
imageUrl
string
Optional reference image URL to animate. When provided, the AI will create a video based on this image.
​
waterMark
string
Optional watermark text. Leave empty for no watermark, or provide text to display in the bottom right corner.

​
Async Processing with Callbacks

For production applications, use callbacks instead of polling: 
{
  "prompt": "A peaceful garden with cherry blossoms swaying in the breeze",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "16:9",
  "callBackUrl": "https://your-app.com/webhook/runway-callback"
}
The system will POST results to your callback URL when generation completes.

Learn More About Callbacks

Complete guide to implementing and handling Runway API callbacks

​
Video Extension Workflow

Create longer video sequences by extending existing videos:
  1. Generate Initial Video: Create a base video using text or image input
  2. Check Completion: Wait for the initial video to complete successfully
  3. Extend Video: Use the original task ID to create an extension
  4. Chain Extensions: Repeat the process to create even longer sequences
// Step 1: Generate initial video
const initialResponse = await generateVideo({
  prompt: "A cat starts dancing in a colorful room",
  duration: 5,
  quality: "720p",
  aspectRatio: "16:9"
});

// Step 2: Wait for completion and extend
const extendResponse = await extendVideo({
  taskId: initialResponse.data.taskId,
  prompt: "The cat spins around with increasing energy and excitement",
  quality: "720p"
});

​
Best Practices

​
Status Codes

​
200
Success
Task created successfully or request completed
​
400
Bad Request
Invalid request parameters or malformed JSON
​
401
Unauthorized
Missing or invalid API key
​
402
Insufficient Credits
Account doesn’t have enough credits for the operation
​
422
Validation Error
Request parameters failed validation checks
​
429
Rate Limited
Too many requests - implement backoff strategy
​
500
Server Error
Internal server error - contact support if persistent

​
Video Storage and Expiration

Generated videos are stored for 14 days before automatic deletion. Download and save your videos within this timeframe.
  • Video URLs remain accessible for 14 days after generation
  • The expireFlag in the response indicates if a video has expired (0 = active, 1 = expired)
  • Plan your workflow to download or process videos before expiration
  • Consider implementing automated download systems for production use

​
Next Steps

Generate Videos

Complete API reference for video generation

Extend Videos

Learn how to extend videos for longer sequences

Callback Setup

Implement webhooks for async processing

Task Details

Query and monitor task status

​
Support

Need help? Our technical support team is here to assist you.
Ready to start generating amazing AI videos? Get your API key and begin creating today!