Generate Aleph Video

Edit and transform existing footage with text-guided video-to-video using Runway Aleph.

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: "apikley"

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.apikley.ru/api/v1/aleph/generate" \
  -H "Authorization: Bearer APIKLEY_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": "apikley",
    "uploadCn": false
  }'

const generateAlephVideo = async (apiKey, options) => {
  const response = await fetch('https://api.apikley.ru/api/v1/aleph/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: options.prompt,
      videoUrl: options.videoUrl,
      callBackUrl: options.callBackUrl,
      waterMark: options.waterMark || '',
      uploadCn: options.uploadCn || false
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const result = await response.json();
  return result;
};

// Usage example
try {
  const result = await generateAlephVideo('YOUR_API_KEY', {
    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: 'apikley',
    uploadCn: false
  });
  
  console.log('Task created:', result.data.taskId);
} catch (error) {
  console.error('Error:', error.message);
}

import requests
import json

def generate_aleph_video(api_key, prompt, image_url, callback_url=None, watermark='', upload_cn=False):
    """
    Generate an Aleph video from an image using text prompt
    
    Args:
        api_key (str): Your API key
        prompt (str): Text description for video animation
        image_url (str): URL of the reference image
        callback_url (str, optional): Webhook URL for completion notification
        watermark (str, optional): Watermark text for the video
        upload_cn (bool, optional): Use China storage (True) or global storage (False)
    
    Returns:
        dict: API response containing task ID
    """
    url = "https://api.apikley.ru/api/v1/aleph/generate"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "prompt": prompt,
        "videoUrl": video_url,
        "waterMark": watermark,
        "uploadCn": upload_cn
    }
    
    if callback_url:
        payload["callBackUrl"] = callback_url
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes
        
        result = response.json()
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        raise
    except json.JSONDecodeError as e:
        print(f"JSON decode error: {e}")
        raise

# Usage example
if __name__ == "__main__":
    api_key = "YOUR_API_KEY"
    
    try:
        result = generate_aleph_video(
            api_key=api_key,
            prompt="A majestic eagle soaring through mountain clouds at sunset with cinematic camera movement",
            image_url="https://example.com/eagle-image.jpg",
            callback_url="https://api.example.com/callback",
            watermark="apikley",
            upload_cn=False
        )
        
        print(f"Task created successfully: {result['data']['taskId']}")
        
    except Exception as e:
        print(f"Error generating video: {e}")

<?php

class AlephVideoGenerator {
    private $apiKey;
    private $baseUrl = 'https://api.apikley.ru';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    /**
     * Generate an Aleph video from a video
     */
    public function generateVideo($prompt, $videoUrl, $options = []) {
        $url = $this->baseUrl . '/api/v1/aleph/generate';
        
        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        $payload = [
            'prompt' => $prompt,
            'videoUrl' => $videoUrl,
            'waterMark' => $options['waterMark'] ?? '',
            'uploadCn' => $options['uploadCn'] ?? false
        ];
        
        if (isset($options['callBackUrl'])) {
            $payload['callBackUrl'] = $options['callBackUrl'];
        }
        
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_FOLLOWLOCATION => true
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        
        if ($error) {
            throw new Exception("cURL error: " . $error);
        }
        
        if ($httpCode !== 200) {
            throw new Exception("HTTP error: " . $httpCode);
        }
        
        $result = json_decode($response, true);
        
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new Exception("JSON decode error: " . json_last_error_msg());
        }
        
        return $result;
    }
}

// Usage example
try {
    $generator = new AlephVideoGenerator('YOUR_API_KEY');
    
    $result = $generator->generateVideo(
        'A majestic eagle soaring through mountain clouds at sunset with cinematic camera movement',
        'https://example.com/eagle-image.jpg',
        [
            'callBackUrl' => 'https://api.example.com/callback',
            'waterMark' => 'apikley',
            'uploadCn' => false
        ]
    );
    
    echo "Task created successfully: " . $result['data']['taskId'] . "\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

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

400 Bad Request
401 Unauthorized
422 Validation Error
451 Image Access Error

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

{
  "code": 401,
  "msg": "Unauthorized",
  "data": null
}

Common causes:

Missing Authorization header
Invalid or expired API key
Incorrectly formatted Bearer token

{
  "code": 422,
  "msg": "Validation failed",
  "data": null
}

Common causes:

Prompt exceeds maximum character limit
Image URL is not accessible
Invalid parameter values

{
  "code": 451,
  "msg": "Failed to fetch the image",
  "data": null
}

Common causes:

Image URL returns 404 or other error
Image is behind authentication
Network connectivity issues
Unsupported image format

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.apikley.ru/api/v1/aleph/record-detail?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer APIKLEY_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

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

Crafting Effective Prompts

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”

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

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 support@apikley.ru for assistance with the Runway Alpeh API.

Rate limits and quotas are enforced by Apikley and may differ from upstream providers.

OpenAPI

runway-api/runway-aleph-api.json post /api/v1/aleph/generate

openapi: 3.0.0
info:
  title: Runway Alpeh API
  description: Apikley Runway Alpeh API Documentation
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@apikley.ru
servers:
  - url: https://api.apikley.ru
    description: API Server
security:
  - BearerAuth: []
paths:
  /api/v1/aleph/generate:
    post:
      summary: Generate Aleph Video
      description: >-
        Create dynamic AI-generated videos using video-to-video transformation
        with Runway Aleph model.


        ### Usage Guide

        - Transform existing videos based on text prompts using AI
        video-to-video generation

        - Enhanced video creation with style transfer and content modification

        - Suitable for video editing, style transformation, and creative video
        enhancement


        ### Parameter Details

        - `prompt` describes how you want to transform the input video

        - `videoUrl` provides the reference video for AI transformation
        (required)

        - `waterMark` optional watermark text for branding

        - `uploadCn` controls storage location for generated videos

        - `aspectRatio` optional video aspect ratio. Options: `16:9`, `9:16`,
        `4:3`, `3:4`, `1:1`, `21:9`

        - `seed` optional random seed for reproducible generation

        - `referenceImage` optional reference image URL to influence the style
        or content


        ### Developer Notes

        - Generated videos are stored for 14 days before automatic deletion

        - All requests require both prompt and videoUrl parameters

        - Use callbacks for efficient asynchronous processing
      operationId: generate-aleph-video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - videoUrl
              properties:
                prompt:
                  type: string
                  description: >-
                    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:
                  type: string
                  description: >-
                    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:
                  type: string
                  description: >-
                    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](https://docs.apikley.ru/runway-api/generate-aleph-video-callbacks)

                    - Alternatively, use the Get Aleph Video Details endpoint to
                    poll task status
                  example: https://api.example.com/callback
                waterMark:
                  type: string
                  description: >-
                    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: apikley
                uploadCn:
                  type: boolean
                  description: >-
                    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
                  default: false
                aspectRatio:
                  type: string
                  description: Video aspect ratio.
                  enum:
                    - '16:9'
                    - '9:16'
                    - '4:3'
                    - '3:4'
                    - '1:1'
                    - '21:9'
                  example: '16:9'
                seed:
                  type: integer
                  description: Random seed. Set for reproducible generation.
                  example: 123456
                referenceImage:
                  type: string
                  format: uri
                  description: >-
                    Reference image URL to influence the style or content of the
                    output.
                  example: https://example.com/reference.jpg
            example:
              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: apikley
              uploadCn: false
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 401
                          - 404
                          - 422
                          - 451
                          - 455
                          - 500
                        description: >-
                          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
                      msg:
                        type: string
                        description: Error message when code != 200
                        example: success
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: >-
                              Unique identifier for the generation task, can be
                              used with `Get Aleph Video Details` to query task
                              status
                            example: ee603959-debb-48d1-98c4-a6d1c717eba6
              example:
                code: 200
                msg: success
                data:
                  taskId: ee603959-debb-48d1-98c4-a6d1c717eba6
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        onVideoGenerated:
          '{$request.body#/callBackUrl}':
            post:
              summary: Aleph Video Generation Completion Callback
              description: >-
                When Aleph video generation is complete, the system will send a
                POST request to the provided callback URL to notify the result
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      required:
                        - code
                        - data
                        - msg
                      properties:
                        code:
                          type: integer
                          description: Status code, 200 indicates success
                          example: 200
                        msg:
                          type: string
                          description: Status message
                          example: All generated successfully.
                        data:
                          type: object
                          required:
                            - image_url
                            - task_id
                            - video_id
                            - video_url
                          properties:
                            image_url:
                              type: string
                              description: Cover image URL of the generated video
                              example: https://file.com/m/xxxxxxxx.png
                            task_id:
                              type: string
                              description: Task ID
                              example: ee603959-debb-48d1-98c4-a6d1c717eba6
                            video_id:
                              type: string
                              description: Video ID
                              example: 485da89c-7fca-4340-8c04-101025b2ae71
                            video_url:
                              type: string
                              description: Accessible video URL, valid for 14 days
                              example: https://file.com/k/xxxxxxx.mp4
              responses:
                '200':
                  description: Callback received successfully
                  content:
                    application/json:
                      schema:
                        allOf:
                          - type: object
                            properties:
                              code:
                                type: integer
                                enum:
                                  - 200
                                  - 400
                                  - 500
                                description: >-
                                  Response status code


                                  - **200**: Success - Request has been
                                  processed successfully

                                  - **400**: Inappropriate content detected.
                                  Please replace the image or video.

                                  Incorrect image format.

                                  Please try again later. You can upgrade to
                                  Standard membership to start generating now.

                                  Reached the limit for concurrent generations.

                                  Unsupported width or height. Please adjust the
                                  size and try again.

                                  Upload failed due to network reasons, please
                                  re-enter.

                                  Your prompt was caught by our AI moderator.
                                  Please adjust it and try again!

                                  Your prompt/negative prompt cannot exceed 2048
                                  characters. Please check if your input is too
                                  long.

                                  Your video creation prompt contains NSFW
                                  content, which isn't allowed under our policy.
                                  Kindly revise your prompt and generate again.

                                  - **500**: Server Error - An unexpected error
                                  occurred while processing the request
                              msg:
                                type: string
                                description: Error message when code != 200
                                example: success
                      example:
                        code: 200
                        msg: success
components:
  responses:
    Error:
      description: Server Error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All APIs require authentication via Bearer Token.


        Get API Key:

        1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
        API Key


        Usage:

        Add to request header:

        Authorization: Bearer APIKLEY_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

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt

Getting Started

Veo3 API

Suno API

Runway API

Image Models

Video Models

Audio Models

Luma API

Flux Kontext API

4o Image API

File Upload API

Common API

Runway api generate aleph video

Generate Aleph Video

Overview

Authentication

Request Body

Code Examples

Response Format

Error Responses

Next Steps

Get Task Details

Callback Implementation

Best Practices

Get Task Details

Callback Guide

OpenAPI

​Generate Aleph Video

​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

​OpenAPI

Generate Aleph Video

Overview

Authentication

Request Body

Code Examples

Response Format

Error Responses

Next Steps

Best Practices

Related Endpoints

OpenAPI