检索有关您的 Runway Alpeh 视频生成任务的详细信息，包括当前状态、生成参数、视频 URL 和错误详情。此端点对于监控任务进度和访问已完成的视频至关重要。
如果您不使用回调，请使用此端点轮询任务状态，或检索已完成任务的详细信息。
身份验证
用于 API 身份验证的 Bearer token。从 API 密钥管理页面 获取您的 API 密钥。格式：Bearer YOUR_API_KEY 查询参数
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 审查员捕获。请调整后重试！"
}
}
响应字段
HTTP 状态码
200：请求成功401：未授权 - API 密钥无效404：未找到任务422：任务 ID 格式无效500：服务器错误
任务详情和状态信息
包含生成视频信息的响应数据（如果未完成则为 null）
视频生成完成时的时间戳（如果未完成则为 null）
任务状态理解
了解任务状态有助于您在应用程序中处理各种场景：
状态：successFlag: 0 且没有 errorMessage应该做什么：继续轮询，生成正在进行中典型持续时间：2-15 分钟，取决于复杂性和系统负载
错误处理
原因：无效或不存在的任务 ID响应：{
"code": 404,
"msg": "任务未找到",
"data": null
}
原因：无效或缺少 API 密钥响应：{
"code": 401,
"msg": "未授权",
"data": null
}
原因：视频生成过程中的各种问题常见失败消息：
- “您的提示词被我们的 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
};
}
相关文档
所有 API 都需要通过 Bearer Token 进行身份验证。
获取 API 密钥：
- 访问 API 密钥管理页面 获取您的 API 密钥
使用方法：
在请求头中添加：
Authorization: Bearer YOUR_API_KEY
注意：
- 请确保您的 API 密钥安全，不要与他人分享
- 如果您怀疑 API 密钥已泄露，请立即在管理页面中重置
Aleph 视频生成任务的唯一标识符。这是创建 Aleph 视频时返回的 taskId。
响应状态码
- 200: 成功 - 请求已成功处理
- 401: 未授权 - 身份验证凭据缺失或无效
- 404: 未找到 - 请求的资源或端点不存在
- 422: 验证错误 - 请求参数验证失败
- 429: 速率限制 - 此资源的请求限制已超出
- 451: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。
- 455: 服务不可用 - 系统当前正在维护中
- 500: 服务器错误 - 处理请求时发生意外错误
可用选项:
200,
401,
404,
422,
429,
451,
455,
500
