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

​
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

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:

  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

Response

200
application/json

Request successful

The response is of type object.