Skip to main content
POST
/
api
/
v1
/
aleph
/
generate
Generate Aleph Video
curl --request POST \
  --url https://api.kie.ai/api/v1/aleph/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A majestic eagle soaring through mountain clouds at sunset with cinematic camera movement",
  "videoUrl": "https://example.com/input-video.mp4",
  "callBackUrl": "https://api.example.com/callback",
  "waterMark": "kie.ai",
  "uploadCn": false
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}

​
Overview

Runway Aleph is an in-context video model for professional video-to-video editing. This endpoint applies text-driven transformations—object addition/removal, relighting, style changes, and new camera/viewpoints—while preserving the motion and timing of your source clip. Current limitation: outputs are capped at 5 seconds; if your input video exceeds 5 seconds, only the first 5 seconds will be processed.
The Runway Aleph API requires both a text prompt and a reference video URL to generate transformed videos. The AI will modify and enhance the provided video according to your text description.

​
Authentication

​
Authorization
string
required
Bearer token for API authentication. Get your API key from the API Key Management Page.Format: Bearer YOUR_API_KEY

​
Request Body

​
prompt
string
required
Descriptive text that guides how the reference video should be transformed. Be specific about movements, camera angles, and visual effects you want to see in the generated video.Best Practices:
  • Focus on transformations and style changes rather than describing what’s already in the video
  • Include camera movement descriptions (e.g., “slow zoom in”, “orbital rotation”)
  • Add temporal elements (e.g., “gradually”, “smoothly”, “suddenly”)
  • Specify lighting and atmosphere changes if desired
Example: "Transform into a dreamy watercolor painting style with soft flowing movements"
​
videoUrl
string
required
URL of the reference video to transform. The video should be publicly accessible via HTTPS.Requirements:
  • Maximum file size: 10MB
  • Must be accessible via HTTPS
Example: "https://example.com/input-video.mp4"
​
callBackUrl
string
Optional webhook URL to receive completion notifications. When provided, the system will POST task results to this URL when video generation completes.Callback Benefits:
  • Eliminates need for polling task status
  • Immediate notification when generation completes
  • Includes complete video information in the callback payload
For detailed callback format and implementation guide, see Aleph Video Generation Callbacks.Example: "https://api.example.com/webhook/aleph-callback"
​
waterMark
string
Optional watermark text to display on the generated video. Leave empty or omit for no watermark.Details:
  • Text will appear in the bottom corner of the video
  • Supports alphanumeric characters and basic symbols
  • Recommended length: 1-20 characters for optimal visibility
Example: "kie.ai"
​
uploadCn
boolean
Storage location selection for the generated video.Options:
  • false (default): Global S3/R2 storage - optimal for international users
  • true: Alibaba Cloud OSS storage - recommended for users in China
Example: false
​
aspectRatio
string
Optional video aspect ratio. One of: 16:9, 9:16, 4:3, 3:4, 1:1, 21:9.
Choose an aspect ratio that matches your target platform (e.g., 9:16 for mobile vertical, 16:9 for desktop/widescreen).
Example: 16:9
​
seed
integer
Optional random seed for reproducible generation. Use the same seed to get consistent results across runs.Example: 123456
​
referenceImage
string
Optional reference image URL (URI). Influences the style or content of the output.Example: https://example.com/reference.jpg

​
Code Examples

curl -X POST "https://api.kie.ai/api/v1/aleph/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A majestic eagle soaring through mountain clouds at sunset with cinematic camera movement",
    "videoUrl": "https://example.com/input-video.mp4",
    "callBackUrl": "https://api.example.com/callback",
    "waterMark": "kie.ai",
    "uploadCn": false
  }'

​
Response Format

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}
​
code
integer
Status code indicating the result of the request
  • 200: Success - Task created successfully
  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Invalid API key
  • 422: Validation Error - Parameter validation failed
  • 451: Image Access Error - Failed to fetch reference image
  • 500: Server Error - Internal error occurred
​
msg
string
Human-readable message describing the response status
​
data
object
Response data containing task information

​
Error Responses

{
  "code": 400,
  "msg": "Invalid request parameters",
  "data": null
}
Common causes:
  • Missing required parameters (prompt or videoUrl)
  • Invalid video URL format
  • Malformed JSON in request body

​
Next Steps

After successfully creating a video generation task, you have several options:
1

Monitor Task Status

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

Get Task Details

Complete guide to checking task status and retrieving results
2

Handle Callbacks (Recommended)

If you provided a callBackUrl, implement a webhook endpoint to receive completion notifications:

Callback Implementation

Learn how to handle callback notifications efficiently
3

Download and Process Results

Once generation completes, download your video and thumbnail:
// Example: Download video after completion
const downloadVideo = async (videoUrl, filename) => {
  const response = await fetch(videoUrl);
  const buffer = await response.arrayBuffer();
  // Save to file or process as needed
};

​
Best Practices

Choose High-Quality Source Images:
  • Use images with clear subjects and good lighting
  • Ensure minimum resolution of 512x512 pixels
  • Avoid heavily compressed or low-quality images
  • Select images with clear focal points for better animation results
Composition Considerations:
  • Images with central subjects work best for animation
  • Consider how camera movements will affect the composition
  • Avoid images with too much visual complexity in backgrounds
Focus on Movement and Action:
  • Describe how elements in the image should move or change
  • Include camera movement descriptions (zoom, pan, rotate)
  • Specify the pace and style of movements (slow, dramatic, smooth)
Examples of Good Prompts:
  • “The eagle spreads its wings and soars upward with majestic slow-motion flight”
  • “Camera slowly pulls back revealing the vast mountain landscape behind the subject”
  • “Gentle wind causes the leaves to rustle while sunlight filters through dynamically”
Implement Robust Error Handling:
const generateWithRetry = async (params, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await generateAlephVideo(params);
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};
Handle Different Error Types:
  • Network errors: Retry with exponential backoff
  • Authentication errors: Check and refresh API key
  • Validation errors: Fix parameters before retry
  • Rate limiting: Implement proper backoff strategies
Use Callbacks for Efficiency:
  • Implement webhook endpoints instead of polling
  • Ensure your callback URL is publicly accessible and secure
  • Handle callback failures with proper logging
Monitor API Usage:
  • Track your API usage and credit consumption
  • Implement rate limiting on your end to avoid hitting API limits
  • Log all requests and responses for debugging
Storage Considerations:
  • Choose appropriate uploadCn setting based on your user base
  • Plan for the 14-day video retention period
  • Implement automatic download systems for important content

Get Task Details

Check generation status and retrieve video URLs

Callback Guide

Implement webhooks for async notifications
Need Help? Contact our support team at [email protected] for assistance with the Runway Alpeh API.

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
​
prompt
string
required

Descriptive text that guides the AI video generation. Be specific about subject, action, style, and setting. Describes how to animate or modify the reference image content.

Example:

"A majestic eagle soaring through mountain clouds at sunset with cinematic camera movement"

​
videoUrl
string
required

Reference video URL to base the video-to-video generation on. The AI will transform and enhance this video according to the prompt.

Example:

"https://example.com/input-video.mp4"

​
callBackUrl
string

The URL to receive AI video generation task completion updates.

  • System will POST task status and results to this URL when video generation completes
  • Callback includes generated video URLs, cover images, and task information
  • Your callback endpoint should accept POST requests with JSON payload containing video results
  • For detailed callback format and implementation guide, see Aleph Video Generation Callbacks
  • Alternatively, use the Get Aleph Video Details endpoint to poll task status
Example:

"https://api.example.com/callback"

​
waterMark
string

Optional watermark text content. An empty string indicates no watermark, while a non-empty string will display the specified text as a watermark in the video.

Example:

"kie.ai"

​
uploadCn
boolean
default:false

Upload method selection. Default value is false (S3/R2), set to true for Alibaba Cloud OSS upload, set to false for overseas R2 server upload.

Example:

false

​
aspectRatio
enum<string>

Video aspect ratio.

Available options:
16:9,
9:16,
4:3,
3:4,
1:1,
21:9
Example:

"16:9"

​
seed
integer

Random seed. Set for reproducible generation.

Example:

123456

​
referenceImage
string<uri>

Reference image URL to influence the style or content of the output.

Example:

"https://example.com/reference.jpg"

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 404: Not Found - The requested resource or endpoint does not exist
  • 422: Validation Error - The request parameters failed validation checks.The request parameters are incorrect, please check the parameters.
  • 451: Unauthorized - Failed to fetch the image. Kindly verify any access limits set by you or your service provider.
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
Available options:
200,
401,
404,
422,
451,
455,
500
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object