Skip to main content

​
Get Aleph Video Details

Retrieve comprehensive information about Runway Alpeh video generation tasks

​
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.apikley.ru/api/v1/aleph/record-info?taskId=ee603959-debb-48d1-98c4-a6d1c717eba6" \
  -H "Authorization: Bearer APIKLEY_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

​
Task Status Understanding

Understanding the task status helps you handle various scenarios in your application:
Status: successFlag: 0 and no errorMessageWhat to do: Continue polling, generation is in progressTypical duration: 2-15 minutes depending on complexity and system load

​
Error Handling

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

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');
}
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")
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.apikley.ru/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.apikley.ru/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.
Rate limits and quotas are enforced by Apikley and may differ from upstream providers.

​
OpenAPI

runway-api/runway-aleph-api.json get /api/v1/aleph/record-info
openapi: 3.0.0
info:
  title: Runway Alpeh API
  description: Apikley Runway Alpeh API Documentation
  version: 1.0.0
  contact:
    name: Technical Support
    email: [email protected]
servers:
  - url: https://api.apikley.ru
    description: API Server
security:
  - BearerAuth: []
paths:
  /api/v1/aleph/record-info:
    get:
      summary: Get Aleph Video Details
      description: >-
        Retrieve comprehensive information about an Aleph AI-generated video
        task.


        ### Usage Guide

        - Check the status of an Aleph video generation task

        - Access video URLs when generation is complete

        - Troubleshoot failed generation attempts


        ### Status Descriptions

        - `successFlag`: 1 = success, 0 = failed or in progress

        - Video links are valid for 14 days after completion

        - Use this endpoint to poll task status if not using callbacks


        ### Developer Notes

        - The response includes detailed task information including creation
        time, completion time, and error details

        - Parameter JSON contains the original generation request parameters
      operationId: get-aleph-video-details
      parameters:
        - name: taskId
          in: query
          description: >-
            Unique identifier of the Aleph video generation task. This is the
            taskId returned when creating an Aleph video.
          required: true
          schema:
            type: string
          example: ee603959-debb-48d1-98c4-a6d1c717eba6
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 401
                          - 404
                          - 422
                          - 429
                          - 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

                          - **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
                      msg:
                        type: string
                        description: Status message
                        example: success
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: >-
                              Unique identifier of the Aleph AI video generation
                              task
                            example: ee603959-debb-48d1-98c4-a6d1c717eba6
                          paramJson:
                            type: string
                            description: >-
                              JSON string containing the original generation
                              request parameters
                            example: >-
                              {"prompt":"A majestic eagle soaring through
                              mountain
                              clouds","videoUrl":"https://example.com/input-video.mp4"}
                          response:
                            type: object
                            description: >-
                              Response data containing generated video
                              information
                            properties:
                              taskId:
                                type: string
                                description: Task ID associated with this generation
                                example: ee603959-debb-48d1-98c4-a6d1c717eba6
                              resultVideoUrl:
                                type: string
                                description: >-
                                  URL to access and download the generated
                                  video, valid for 14 days
                                example: https://file.com/k/xxxxxxx.mp4
                              resultImageUrl:
                                type: string
                                description: >-
                                  URL of a thumbnail image from the generated
                                  video
                                example: https://file.com/m/xxxxxxxx.png
                          completeTime:
                            type: string
                            format: date-time
                            description: Timestamp when the video generation was completed
                            example: '2023-08-15T14:30:45Z'
                          createTime:
                            type: string
                            format: date-time
                            description: Timestamp when the task was created
                            example: '2023-08-15T14:25:00Z'
                          successFlag:
                            type: integer
                            format: int32
                            description: >-
                              Success status: 1 = success, 0 = failed or in
                              progress
                            enum:
                              - 0
                              - 1
                            example: 1
                          errorCode:
                            type: integer
                            format: int32
                            description: Error code when generation fails (0 if successful)
                            example: 0
                          errorMessage:
                            type: string
                            description: >-
                              Detailed error message explaining the reason for
                              failure (empty if successful)
                            example: ''
              example:
                code: 200
                msg: success
                data:
                  taskId: ee603959-debb-48d1-98c4-a6d1c717eba6
                  paramJson: >-
                    {"prompt":"A majestic eagle soaring through mountain clouds
                    at sunset","videoUrl":"https://example.com/input-video.mp4"}
                  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: ''
        '500':
          $ref: '#/components/responses/Error'
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