Generate Aleph Video

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

Show data properties

taskId

string

Unique identifier for the video generation task. Use this ID to check task status or retrieve results.

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:

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

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

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

Optimizing Image Selection

Crafting Effective Prompts

Error Handling and Retry Logic

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

Production Deployment Tips

Get Task Details

Check generation status and retrieve video URLs

Callback Guide

Implement webhooks for async notifications

Need Help? Contact our support team at support@kie.ai for assistance with the Runway Alpeh API.

Authorizations

Authorization

string

header

required

All APIs require authentication via Bearer Token.

Get API Key:

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

Show child attributes

Aleph

​Overview

​Authentication

​Request Body

​Code Examples

​Response Format

​Error Responses

​Next Steps

Get Task Details

Callback Implementation

​Best Practices

​Related Endpoints

Get Task Details

Callback Guide

Authorizations

Body

Response

Overview

Authentication

Request Body

Code Examples

Response Format

Error Responses

Next Steps

Best Practices

Related Endpoints