获取 Aleph 视频详情

概述

检索有关您的 Runway Alpeh 视频生成任务的详细信息，包括当前状态、生成参数、视频 URL 和错误详情。此端点对于监控任务进度和访问已完成的视频至关重要。

如果您不使用回调，请使用此端点轮询任务状态，或检索已完成任务的详细信息。

身份验证

Authorization

string

必填

用于 API 身份验证的 Bearer token。从 API 密钥管理页面获取您的 API 密钥。格式：Bearer YOUR_API_KEY

查询参数

taskId

string

必填

Alpeh 视频生成任务的唯一标识符。这是您创建视频生成请求时返回的 taskId。示例： ee603959-debb-48d1-98c4-a6d1c717eba6

代码示例

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

响应格式

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "paramJson": "{\"prompt\":\"一只雄鹰在夕阳下的山间云雾中翱翔\",\"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\":\"一只雄鹰在夕阳下的山间云雾中翱翔\",\"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\":\"一只雄鹰在夕阳下的山间云雾中翱翔\",\"imageUrl\":\"https://example.com/eagle-image.jpg\"}",
    "response": null,
    "completeTime": null,
    "createTime": "2023-08-15T14:25:00Z",
    "successFlag": 0,
    "errorCode": 400,
    "errorMessage": "您的提示词被我们的 AI 审查员捕获。请调整后重试！"
  }
}

响应字段

code

integer

HTTP 状态码

200：请求成功
401：未授权 - API 密钥无效
404：未找到任务
422：任务 ID 格式无效
500：服务器错误

msg

string

可读的响应消息

data

object

任务详情和状态信息

显示 data 属性

taskId

string

Alpeh 视频生成任务的唯一标识符

paramJson

string

包含原始生成请求参数的 JSON 字符串

response

object

包含生成视频信息的响应数据（如果未完成则为 null）

显示 response 属性

taskId

string

与此生成关联的任务 ID

resultVideoUrl

string

下载生成视频的直接 URL（有效期 14 天）

resultImageUrl

string

从视频中提取的缩略图 URL

completeTime

string

视频生成完成时的时间戳（如果未完成则为 null）

createTime

string

任务创建时的时间戳

successFlag

integer

成功状态指示符

1：视频生成成功
0：生成失败或仍在进行中

errorCode

integer

生成失败时的错误码（成功时为 0）

400：内容政策违规或技术错误

errorMessage

string

解释失败原因的详细错误消息（成功时为空）

任务状态理解

了解任务状态有助于您在应用程序中处理各种场景：

处理中
成功
失败

状态：successFlag: 0 且没有 errorMessage应该做什么：继续轮询，生成正在进行中典型持续时间：2-15 分钟，取决于复杂性和系统负载

状态：successFlag: 1应该做什么：从 response 对象访问视频和缩略图 URL视频可用性：完成后 14 天内 URL 有效

状态：successFlag: 0 且有 errorMessage应该做什么：检查 errorMessage 了解详情，如需要修改参数，适当时重试常见原因：内容政策违规，图像访问问题，技术错误

错误处理

任务未找到 (404)

原因：无效或不存在的任务 ID响应：

{
  "code": 404,
  "msg": "任务未找到",
  "data": null
}

解决方案：验证任务 ID 是否正确，且来自有效的生成请求

未授权 (401)

原因：无效或缺少 API 密钥响应：

{
  "code": 401,
  "msg": "未授权",
  "data": null
}

解决方案：检查您的 API 密钥并确保在 Authorization 头中格式正确

生成失败

原因：视频生成过程中的各种问题常见失败消息：

“您的提示词被我们的 AI 审查员捕获” - 内容政策违规
“获取图像失败” - 图像 URL 无法访问
“检测到不当内容” - 图像内容违规
“由于网络原因上传失败” - 临时技术问题

解决方案：根据错误消息修改提示词或图像，然后重试

轮询最佳实践

高效的轮询策略

推荐间隔：

前 5 分钟：每 30 秒检查一次
接下来 10 分钟：每 60 秒检查一次
15 分钟后：每 2-3 分钟检查一次

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('轮询超时');
}

超时处理

设置合理的超时：

大多数视频在 10-15 分钟内完成
设置最大超时为 30 分钟
对网络错误实现指数退避

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
            
            # 基于检查次数的动态间隔
            interval = min(30 + (check_count * 10), 180)
            time.sleep(interval)
            check_count += 1
            
        except Exception as e:
            print(f"轮询错误：{e}")
            time.sleep(60)  # 错误时等待更长时间
    
    raise TimeoutError("任务轮询超时")

错误恢复

优雅地处理临时失败：

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;
      }
      
      // 成功请求时重置重试计数
      retryCount = 0;
      await new Promise(resolve => setTimeout(resolve, 30000));
      
    } catch (error) {
      retryCount++;
      console.warn(`轮询尝试 ${retryCount} 失败：`, error.message);
      
      if (retryCount >= maxRetries) {
        throw new Error(`轮询在 ${maxRetries} 次重试后失败`);
      }
      
      // 重试的指数退避
      const delay = Math.pow(2, retryCount) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

集成示例

用于视频生成的 React Hook

import { useState, useEffect } from 'react';

export function useAlephVideoGeneration(apiKey) {
  const [tasks, setTasks] = useState(new Map());
  
  const generateVideo = async (prompt, imageUrl, options = {}) => {
    // 开始生成
    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;
    
    // 添加到跟踪
    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;
  };
  
  // 活动任务的自动轮询
  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(`检查任务 ${task.id} 时出错：`, error);
        }
      }
    }, 30000);
    
    return () => clearInterval(interval);
  }, [tasks]);
  
  return {
    tasks: Array.from(tasks.values()),
    generateVideo,
    checkTask
  };
}

生成 Aleph 视频

学习如何创建视频生成请求

回调集成

实现 webhook 而不是轮询以提高效率

需要帮助？ 请联系我们的支持团队 [email protected] 获取 Runway Alpeh API 的帮助。

授权

Authorization

string

header

必填

所有 API 都需要通过 Bearer Token 进行身份验证。

获取 API 密钥：

访问 API 密钥管理页面获取您的 API 密钥

使用方法：在请求头中添加： Authorization: Bearer YOUR_API_KEY

注意：

请确保您的 API 密钥安全，不要与他人分享
如果您怀疑 API 密钥已泄露，请立即在管理页面中重置

查询参数

taskId

string

必填

Aleph 视频生成任务的唯一标识符。这是创建 Aleph 视频时返回的 taskId。

响应

请求成功

code

enum<integer>

响应状态码

200: 成功 - 请求已成功处理
401: 未授权 - 身份验证凭据缺失或无效
404: 未找到 - 请求的资源或端点不存在
422: 验证错误 - 请求参数验证失败
429: 速率限制 - 此资源的请求限制已超出
451: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。
455: 服务不可用 - 系统当前正在维护中
500: 服务器错误 - 处理请求时发生意外错误

可用选项:

200,

401,

404,

422,

429,

451,

455,

500

msg

string

状态消息

示例:

"success"

data

object

显示子属性

Aleph

​概述

​身份验证

​查询参数

​代码示例

​响应格式

​成功响应

​响应字段

​任务状态理解

​错误处理

​轮询最佳实践

​集成示例

​用于视频生成的 React Hook

​相关文档

生成 Aleph 视频

回调集成

授权

查询参数

响应

概述

身份验证

查询参数

代码示例

响应格式

成功响应

响应字段

任务状态理解

错误处理

轮询最佳实践

集成示例

用于视频生成的 React Hook

相关文档