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
Authentication Header
Quick Start Guide
Step 1: Generate Your First Video
Start with a simple text-to-video generation request:Step 2: Check Task Status
Use the returned task ID to check the generation status:Response Format
Successful Response:Generation Types
Generate videos from text descriptions:
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 10-second durations
1080p Full HD
Premium qualityHigher resolution for professional contentOnly available for 5-second videos
Key Parameters
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”)
Video duration in seconds. Choose from:
5
- 5-second video (compatible with both 720p and 1080p)10
- 10-second video (only compatible with 720p)
Video resolution quality:
720p
- HD quality, compatible with all durations1080p
- Full HD quality, only available for 5-second videos
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 format3:4
- Portrait orientation
Optional reference image URL to animate. When provided, the AI will create a video based on this image.
Optional watermark text. Leave empty for no watermark, or provide text to display in the bottom right corner.
Complete Workflow Example
Here’s a complete example that generates a video and waits for completion:Async Processing with Callbacks
For production applications, use callbacks instead of polling:Learn More About Callbacks
Complete guide to implementing and handling Runway API callbacks
Video Extension Workflow
Create longer video sequences by extending existing videos:- Generate Initial Video: Create a base video using text or image input
- Check Completion: Wait for the initial video to complete successfully
- Extend Video: Use the original task ID to create an extension
- Chain Extensions: Repeat the process to create even longer sequences
Best Practices
Prompt Engineering for Videos
Prompt Engineering for Videos
- Focus on actions and movements rather than static descriptions
- Include temporal elements (e.g., “gradually”, “suddenly”, “slowly”)
- Describe camera movements when relevant (e.g., “zoom in”, “pan left”)
- Be consistent with subject and style throughout extensions
Performance Optimization
Performance Optimization
- Use callbacks instead of frequent polling
- Implement proper error handling and retry logic
- Consider video duration vs quality trade-offs
- Cache results and implement efficient storage solutions
Quality and Duration Selection
Quality and Duration Selection
- Choose 720p for longer videos (10 seconds) or when file size matters
- Use 1080p for high-quality short videos (5 seconds only)
- Consider your target platform’s requirements (social media, web, etc.)
- Test different combinations to find optimal settings for your use case
Error Handling
Error Handling
- Always check the response status code
- Implement exponential backoff for retries
- Handle rate limiting gracefully
- Monitor task states and handle failures appropriately
Status Codes
Task created successfully or request completed
Invalid request parameters or malformed JSON
Missing or invalid API key
Account doesn’t have enough credits for the operation
Request parameters failed validation checks
Too many requests - implement backoff strategy
Internal server error - contact support if persistent
Task Status Descriptions
Task has been created and is waiting for processing
Task is in queue waiting to be processed
Task is currently being processed
Task completed successfully
Task generation failed
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.
- Email: support@kie.ai
- Documentation: docs.kie.ai
- API Status: Check our status page for real-time API health
Ready to start generating amazing AI videos? Get your API key and begin creating today!