Runway API Quickstart

Start generating stunning AI videos with the Runway API in minutes

Welcome to the Runway API

The Runway API gives you access to the powerful capabilities of Runway's advanced AI models to generate high-quality AI videos. Whether you're building applications, 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. Please obtain your API key from the API Key Management page.

Please keep your API key secure and never share it publicly. If you suspect your key has been compromised, reset it immediately.

API Base URL

https://api.kie.ai

Authentication Header

Quick Start Guide

Step 1: Generate Your First Video

Start with a simple text-to-video generation request:

Node.js

Python

cURL

Step 2: Check Task Status

Use the returned task ID to check generation status:

Node.js

Python

cURL

Response Format

Success 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

Text-to-Video

Image-to-Video

Video Extension

Generate video from text description:

{
  "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 Quality

Balanced file size and quality, suitable for most applications

Compatible with both 5s and 10s durations

1080p Full HD

Premium Quality

Higher resolution for professional content

Only 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 quickly")

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. Options:

5 - 5-second video (compatible with 720p and 1080p)

10 - 10-second video (compatible only with 720p)

`quality` (string, required)

Video resolution quality:

720p - High definition quality, compatible with all durations

1080p - Full high definition quality, only for 5-second videos

`aspectRatio` (string, required)

Video aspect ratio. Options:

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.

Complete Workflow Example

Here's a complete example of generating a video and waiting for completion:

JavaScript

Python

Asynchronous Processing with Callbacks

For production applications, use callbacks instead of polling:

{
  "prompt": "A peaceful garden with cherry blossoms swaying in a gentle breeze",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "16:9",
  "callBackUrl": "https://your-app.com/webhook/runway-callback"
}

When generation completes, the system will POST the results to your callback URL.

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 status: Wait for initial video to complete successfully

Extend video: Create an extension using the original task ID

Chain extensions: Repeat this process to create longer sequences

Best Practices

Video Prompt Engineering

Focus on actions and movements rather than static descriptions

Include temporal elements (e.g., "gradually", "suddenly", "slowly")

Describe camera movement when relevant (e.g., "zooming in", "panning left")

Maintain consistency in subject and style across extensions

Performance Optimization

Use callbacks instead of frequent polling

Implement proper error handling and retry logic

Consider trade-offs between video duration and quality

Cache results and implement efficient storage solutions

Quality and Duration Selection

Choose 720p for longer videos (10s) or when file size matters

Use 1080p for high-quality short videos (5s only)

Consider requirements of target platforms (social media, web, etc.)

Test different combinations to find the optimal setup for your use case

Error Handling

Always check response status codes

Implement exponential backoff for retries

Handle rate limiting gracefully

Monitor task status and handle failures appropriately

Status Codes

`200` (Success)

Task creation successful 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

Task Status Explanation

`state: wait` (Waiting)

Task created, waiting to be processed

`state: queueing` (Queueing)

Task queued and waiting to be processed

`state: generating` (Generating)

Task currently being processed

`state: success` (Success)

Task completed successfully

`state: fail` (Failed)

Task generation failed

Video Storage and Expiration

Generated videos are stored for 14 days before automatic deletion. Please download and save your videos within this timeframe.

Video URLs remain accessible for 14 days after generation

expireFlag in the response indicates if video is expired (0 = active, 1 = expired)

Plan your workflow to download or process videos before expiration

Consider implementing automatic download systems for production use

Next Steps

Generate Video

Complete API reference for video generation

Extend Video

Learn how to extend videos to create longer sequences

Callback Setup

Implement webhooks for asynchronous processing

Task Details

Query and monitor task status

Support

Need help? Our technical support team is here for 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 start creating today!

Runway API Quickstart

Welcome to the Runway API#

Authentication#

API Base URL#

Authentication Header#

Quick Start Guide#

Step 1: Generate Your First Video#

Step 2: Check Task Status#

Response Format#

Generation Types#

Video Quality Options#

Key Parameters#

prompt (string, required)#

duration (number, required)#

quality (string, required)#

aspectRatio (string, required)#

imageUrl (string)#

waterMark (string)#

Complete Workflow Example#

Asynchronous Processing with Callbacks#

Video Extension Workflow#

Best Practices#

Status Codes#

200 (Success)#

400 (Bad Request)#

401 (Unauthorized)#

402 (Insufficient Credits)#

422 (Validation Error)#

429 (Rate Limited)#

500 (Server Error)#

Task Status Explanation#

state: wait (Waiting)#

state: queueing (Queueing)#

state: generating (Generating)#

state: success (Success)#

state: fail (Failed)#

Video Storage and Expiration#

Next Steps#

Support#

Welcome to the Runway API

Authentication

API Base URL

Authentication Header

Quick Start Guide

Step 1: Generate Your First Video

Step 2: Check Task Status

Response Format

Generation Types

Video Quality Options

Key Parameters

`prompt` (string, required)

`duration` (number, required)

`quality` (string, required)

`aspectRatio` (string, required)

`imageUrl` (string)

`waterMark` (string)

Complete Workflow Example

Asynchronous Processing with Callbacks

Video Extension Workflow

Best Practices

Status Codes

`200` (Success)

`400` (Bad Request)

`401` (Unauthorized)

`402` (Insufficient Credits)

`422` (Validation Error)

`429` (Rate Limited)

`500` (Server Error)

Task Status Explanation

`state: wait` (Waiting)

`state: queueing` (Queueing)

`state: generating` (Generating)

`state: success` (Success)

`state: fail` (Failed)

Video Storage and Expiration

Next Steps

Support