​
Welcome to Runway Aleph API

The Runway Aleph API enables you to generate high-quality AI videos using Runway’s advanced Aleph model. Transform existing videos into enhanced dynamic content with precise text-guided video-to-video transformation, perfect for video editing, style transfer, and creative video enhancement.

Video-to-Video

Transform existing videos with AI-powered style transfer

Task Management

Track and monitor your video generation tasks

Callback Integration

Implement webhooks for efficient async processing

Storage Options

Choose between global and China-specific storage

​
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 image-to-video generation request: 
curl -X POST "https://api.kie.ai/api/v1/aleph/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform into a dreamy watercolor painting style with soft, flowing movements",
    "videoUrl": "https://example.com/input-video.mp4",
    "waterMark": "kie.ai",
    "uploadCn": false
  }'

​
Step 2: Check Task Status

Use the returned task ID to check the generation status: 
curl -X GET "https://api.kie.ai/api/v1/aleph/record-info?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",
    "paramJson": "{\"prompt\":\"A majestic eagle soaring through mountain clouds at sunset\",\"videoUrl\":\"https://example.com/input-video.mp4\"}",
    "response": {
      "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
      "resultVideoUrl": "https://file.com/k/xxxxxxx.mp4",
      "resultImageUrl": "https://file.com/m/xxxxxxxx.png"
    },
    "completeTime": "2023-08-15T14:30:45Z",
    "createTime": "2023-08-15T14:25:00Z",
    "successFlag": 1,
    "errorCode": 0,
    "errorMessage": ""
  }
}

​
Key Features

Transform static images into dynamic videos:
{
  "prompt": "The character starts walking forward with confidence, camera following smoothly",
  "videoUrl": "https://example.com/character-video.mp4",
  "waterMark": "kie.ai"
}

​
Key Parameters

​
prompt
string
required
Text description that guides how the reference image should be animated. Be specific about movements, camera angles, and visual effects.Tips for better prompts:
  • Describe specific movements and actions (e.g., “slowly rotating”, “zooming in”, “panning left”)
  • Include camera movement descriptions (e.g., “cinematic camera movement”, “smooth tracking shot”)
  • Add atmosphere and lighting details (e.g., “dramatic lighting”, “soft morning light”)
  • Specify the style and mood (e.g., “epic cinematic style”, “dreamy and ethereal”)
​
videoUrl
string
required
URL of the reference video to transform. The AI will enhance and modify this video based on your prompt.Video Requirements:
  • Supported formats: MP4, MOV, AVI
  • Recommended resolution: 720p or higher
  • Maximum file size: 10MB
  • Video should be publicly accessible via HTTPS
​
callBackUrl
string
Optional callback URL to receive completion notifications. When provided, the system will POST results to this URL when generation completes.
​
waterMark
string
Optional watermark text to display on the generated video. Leave empty for no watermark, or provide text to display in the bottom corner.
​
uploadCn
boolean
Storage location selection. Default is false (global S3/R2 storage). Set to true for Alibaba Cloud OSS storage (recommended for users in China).

​
Async Processing with Callbacks

For production applications, use callbacks instead of polling: 
{
  "prompt": "A peaceful garden with cherry blossoms swaying in the gentle breeze",
  "videoUrl": "https://example.com/garden-scene.mp4",
  "callBackUrl": "https://your-app.com/webhook/aleph-callback",
  "waterMark": "kie.ai"
}
The system will POST results to your callback URL when generation completes.

Learn More About Callbacks

Complete guide to implementing and handling Runway Alpeh API callbacks

​
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
​
451
Image Access Error
Failed to fetch the reference image - verify image URL and accessibility
​
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 Alpeh video generation

Task Details

Query and monitor task status

Callback Setup

Implement webhooks for async processing

Storage Guide

Choose optimal storage options

​
Support

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