Get Aleph Video Details

Overview

Retrieve detailed information about your Runway Alpeh video generation tasks, including current status, generation parameters, video URLs, and error details. This endpoint is essential for monitoring task progress and accessing completed videos.

Use this endpoint to poll task status if you’re not using callbacks, or to retrieve detailed information about completed tasks.

Authentication

Authorization

string

required

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

Query Parameters

taskId

string

required

Unique identifier of the Alpeh video generation task. This is the taskId returned when you create a video generation request.Example: ee603959-debb-48d1-98c4-a6d1c717eba6

Code Examples

curl -X GET "https://api.kie.ai/api/v1/aleph/record-info?taskId=ee603959-debb-48d1-98c4-a6d1c717eba6" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

Success Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "paramJson": "{\"prompt\":\"A majestic eagle soaring through mountain clouds at sunset\",\"imageUrl\":\"https://example.com/eagle-image.jpg\"}",
    "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": ""
  }
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "paramJson": "{\"prompt\":\"A majestic eagle soaring through mountain clouds at sunset\",\"imageUrl\":\"https://example.com/eagle-image.jpg\"}",
    "response": null,
    "completeTime": null,
    "createTime": "2023-08-15T14:25:00Z",
    "successFlag": 0,
    "errorCode": 0,
    "errorMessage": ""
  }
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "paramJson": "{\"prompt\":\"A majestic eagle soaring through mountain clouds at sunset\",\"imageUrl\":\"https://example.com/eagle-image.jpg\"}",
    "response": null,
    "completeTime": null,
    "createTime": "2023-08-15T14:25:00Z",
    "successFlag": 0,
    "errorCode": 400,
    "errorMessage": "Your prompt was caught by our AI moderator. Please adjust it and try again!"
  }
}

Response Fields

code

integer

HTTP status code

200: Request successful
401: Unauthorized - Invalid API key
404: Task not found
422: Invalid task ID format
500: Server error

msg

string

Human-readable response message

data

object

Task details and status information

Show data properties

taskId

string

Unique identifier of the Alpeh video generation task

paramJson

string

JSON string containing the original generation request parameters

response

object

Response data containing generated video information (null if not completed)

Show response properties

taskId

string

Task ID associated with this generation

resultVideoUrl

string

Direct URL to download the generated video (valid for 14 days)

resultImageUrl

string

URL of thumbnail image extracted from the video

completeTime

string

Timestamp when video generation was completed (null if not completed)

createTime

string

Timestamp when the task was created

successFlag

integer

Success status indicator

1: Video generated successfully
0: Generation failed or still in progress

errorCode

integer

Error code when generation fails (0 if successful)

400: Content policy violation or technical error

errorMessage

string

Detailed error message explaining failure reason (empty if successful)

Task Status Understanding

Understanding the task status helps you handle various scenarios in your application:

Processing
Success
Failed

Status: successFlag: 0 and no errorMessageWhat to do: Continue polling, generation is in progressTypical duration: 2-15 minutes depending on complexity and system load

Status: successFlag: 1What to do: Access video and thumbnail URLs from the response objectVideo availability: URLs are valid for 14 days after completion

Status: successFlag: 0 and has errorMessageWhat to do: Check errorMessage for details, modify parameters if needed, retry if appropriateCommon causes: Content policy violations, image access issues, technical errors

Error Handling

Task Not Found (404)

Cause: Invalid or non-existent task IDResponse:

{
  "code": 404,
  "msg": "Task not found",
  "data": null
}

Solution: Verify the task ID is correct and was returned from a valid generation request

Unauthorized (401)

Cause: Invalid or missing API keyResponse:

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

Solution: Check your API key and ensure it’s properly formatted in the Authorization header

Generation Failed

Cause: Various issues during video generationCommon failure messages:

“Your prompt was caught by our AI moderator” - Content policy violation
“Failed to fetch the image” - Image URL inaccessible
“Inappropriate content detected” - Image content violation
“Upload failed due to network reasons” - Temporary technical issue

Solution: Modify prompt or image based on error message, then retry

Polling Best Practices

Efficient Polling Strategy

Recommended intervals:

First 5 minutes: Check every 30 seconds
Next 10 minutes: Check every 60 seconds
After 15 minutes: Check every 2-3 minutes

async function pollWithBackoff(taskId, apiKey) {
  const intervals = [30, 30, 30, 30, 30, 60, 60, 120, 180];
  
  for (let i = 0; i < intervals.length; i++) {
    const details = await getAlephVideoDetails(apiKey, taskId);
    const state = details.data.state;
    
    if (state === 'success' || state === 'fail') {
      return details;
    }
    
    await new Promise(resolve => 
      setTimeout(resolve, intervals[i] * 1000)
    );
  }
  
  throw new Error('Polling timeout');
}

Timeout Handling

Set reasonable timeouts:

Most videos complete within 10-15 minutes
Set maximum timeout of 30 minutes
Implement exponential backoff for network errors

def poll_with_timeout(api_key, task_id, max_wait=1800):
    start_time = time.time()
    check_count = 0
    
    while time.time() - start_time < max_wait:
        try:
            details = get_aleph_video_details(api_key, task_id)
            state = details['data']['state']
            
            if state in ['success', 'fail']:
                return details
            
            # Dynamic interval based on check count
            interval = min(30 + (check_count * 10), 180)
            time.sleep(interval)
            check_count += 1
            
        except Exception as e:
            print(f"Polling error: {e}")
            time.sleep(60)  # Wait longer on errors
    
    raise TimeoutError("Task polling timeout")

Error Recovery

Handle temporary failures gracefully:

async function robustPolling(taskId, apiKey, maxRetries = 3) {
  let retryCount = 0;
  
  while (retryCount < maxRetries) {
    try {
      const details = await getAlephVideoDetails(apiKey, taskId);
      
      if (details.data.state === 'success' || details.data.state === 'fail') {
        return details;
      }
      
      // Reset retry count on successful request
      retryCount = 0;
      await new Promise(resolve => setTimeout(resolve, 30000));
      
    } catch (error) {
      retryCount++;
      console.warn(`Polling attempt ${retryCount} failed:`, error.message);
      
      if (retryCount >= maxRetries) {
        throw new Error(`Polling failed after ${maxRetries} retries`);
      }
      
      // Exponential backoff for retries
      const delay = Math.pow(2, retryCount) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Integration Examples

React Hook for Video Generation

import { useState, useEffect } from 'react';

export function useAlephVideoGeneration(apiKey) {
  const [tasks, setTasks] = useState(new Map());
  
  const generateVideo = async (prompt, imageUrl, options = {}) => {
    // Start generation
    const response = await fetch('https://api.kie.ai/api/v1/aleph/generate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ prompt, imageUrl, ...options })
    });
    
    const result = await response.json();
    const taskId = result.data.taskId;
    
    // Add to tracking
    setTasks(prev => new Map(prev).set(taskId, {
      id: taskId,
      state: 'wait',
      prompt,
      imageUrl,
      startTime: Date.now()
    }));
    
    return taskId;
  };
  
  const checkTask = async (taskId) => {
    const response = await fetch(
      `https://api.kie.ai/api/v1/aleph/record-info?taskId=${taskId}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    const details = await response.json();
    
    setTasks(prev => {
      const updated = new Map(prev);
      const existing = updated.get(taskId);
      if (existing) {
        updated.set(taskId, {
          ...existing,
          ...details.data,
          lastChecked: Date.now()
        });
      }
      return updated;
    });
    
    return details.data;
  };
  
  // Auto-polling for active tasks
  useEffect(() => {
    const activeTasks = Array.from(tasks.values())
      .filter(task => ['wait', 'queueing', 'generating'].includes(task.state));
    
    if (activeTasks.length === 0) return;
    
    const interval = setInterval(async () => {
      for (const task of activeTasks) {
        try {
          await checkTask(task.id);
        } catch (error) {
          console.error(`Error checking task ${task.id}:`, error);
        }
      }
    }, 30000);
    
    return () => clearInterval(interval);
  }, [tasks]);
  
  return {
    tasks: Array.from(tasks.values()),
    generateVideo,
    checkTask
  };
}

Generate Aleph Video

Learn how to create video generation requests

Callback Integration

Implement webhooks instead of polling for better efficiency

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:

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

Query Parameters

taskId

string

required

Unique identifier of the Aleph video generation task. This is the taskId returned when creating an Aleph video.

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
429: Rate Limited - Request limit has been exceeded for this resource
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,

429,

451,

455,

500

msg

string

Status message

Example:

"success"

data

object

Show child attributes

Aleph

​Overview

​Authentication

​Query Parameters

​Code Examples

​Response Format

​Success Response

​Response Fields

​Task Status Understanding

​Error Handling

​Polling Best Practices

​Integration Examples

​React Hook for Video Generation

​Related Documentation

Generate Aleph Video

Callback Integration

Authorizations

Query Parameters

Response

Overview

Authentication

Query Parameters

Code Examples

Response Format

Success Response

Response Fields

Task Status Understanding

Error Handling

Polling Best Practices

Integration Examples

React Hook for Video Generation

Related Documentation