跳转到主要内容
POST
/
api
/
v1
/
aleph
/
generate
生成 Aleph 视频
curl --request POST \
  --url https://api.kie.ai/api/v1/aleph/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "一只雄鹰在夕阳下的山间云雾中翱翔，配以电影级镜头运动",
  "videoUrl": "https://example.com/input-video.mp4",
  "callBackUrl": "https://api.example.com/callback",
  "waterMark": "kie.ai",
  "uploadCn": false
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}

​
概述

使用 Runway 先进的 Aleph AI 模型将现有视频转换为增强的动态内容。此端点通过文本引导转换实现精确的视频到视频生成，非常适合从现有视频创建增强的视觉内容。
Runway Aleph API 需要文本提示词和参考视频 URL 来生成转换后的视频。AI 将根据您的文本描述对提供的视频进行修改和增强。

​
身份验证

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

​
请求体

​
prompt
string
必填
指导如何对参考视频进行转换的描述性文本。请具体描述您希望在生成的视频中看到的风格变化、效果和修改。最佳实践：
  • 专注于转换和风格变化，而不是描述视频中已有的内容
  • 包含镜头运动描述（例如：“缓慢放大”、“轨道旋转”）
  • 添加时间元素（例如：“逐渐地”、“平滑地”、“突然地”）
  • 如有需要，指定照明和氛围变化
示例： "转换为梦幻水彩画风格，配以柔和流动的运动效果"
​
videoUrl
string
必填
要进行转换的参考视频的 URL。视频应通过 HTTPS 公开访问。要求：
  • 最大文件大小：10MB
  • 必须通过 HTTPS 访问
示例： "https://example.com/input-video.mp4"
​
callBackUrl
string
可选的 webhook URL，用于接收完成通知。当提供时，系统将在视频生成完成时向此 URL 发送 POST 任务结果。回调的好处：
  • 消除轮询任务状态的需要
  • 生成完成时立即通知
  • 在回调负载中包含完整的视频信息
有关详细的回调格式和实施指南，请参阅 Aleph 视频生成回调。示例： "https://api.example.com/webhook/aleph-callback"
​
waterMark
string
可选的水印文本，显示在生成的视频上。留空或省略表示无水印。详情：
  • 文本将出现在视频的底部角落
  • 支持字母数字字符和基本符号
  • 推荐长度：1-20 个字符以获得最佳可见性
示例： "kie.ai"
​
uploadCn
boolean
生成视频的存储位置选择。选项：
  • false（默认）：全球 S3/R2 存储 - 适合国际用户
  • true：阿里云 OSS 存储 - 推荐中国用户使用
示例： false
​
aspectRatio
string
可选的视频纵横比。可选值：16:9、9:16、4:3、3:4、1:1、21:9。
根据目标平台选择合适的纵横比（例如：移动端竖屏推荐 9:16，桌面端宽屏推荐 16:9）。
示例： 16:9
​
seed
integer
可选的随机种子。用于结果可复现，相同的 seed 在相同参数下倾向生成一致的结果。示例： 123456
​
referenceImage
string
可选的参考图像 URL（URI）。用于影响输出的风格或内容。示例： https://example.com/reference.jpg

​
代码示例

curl -X POST "https://api.kie.ai/api/v1/aleph/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只雄鹰在夕阳下的山间云雾中翱翔，配以电影级镜头运动",
    "videoUrl": "https://example.com/input-video.mp4",
    "callBackUrl": "https://api.example.com/callback",
    "waterMark": "kie.ai",
    "uploadCn": false
  }'

​
响应格式

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}
​
code
integer
指示请求结果的状态码
  • 200：成功 - 任务创建成功
  • 400：错误请求 - 参数无效
  • 401：未授权 - API 密钥无效
  • 422：验证错误 - 参数验证失败
  • 451：图像访问错误 - 获取参考图像失败
  • 500：服务器错误 - 发生内部错误
​
msg
string
描述响应状态的可读消息
​
data
object
包含任务信息的响应数据

​
错误响应

{
  "code": 400,
  "msg": "请求参数无效",
  "data": null
}
常见原因：
  • 缺少必需参数（prompt 或 videoUrl）
  • 图像 URL 格式无效
  • 请求体中的 JSON 格式错误

​
下一步

成功创建视频生成任务后，您有几个选择：
1

监控任务状态

使用返回的 taskId 检查生成进度：
curl -X GET "https://api.kie.ai/api/v1/aleph/record-detail?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

获取任务详情

检查任务状态和检索结果的完整指南
2

处理回调（推荐）

如果您提供了 callBackUrl，请实现 webhook 端点来接收完成通知：

回调实现

学习如何高效处理回调通知
3

下载和处理结果

生成完成后，下载您的视频和缩略图：
// 示例：完成后下载视频
const downloadVideo = async (videoUrl, filename) => {
  const response = await fetch(videoUrl);
  const buffer = await response.arrayBuffer();
  // 保存到文件或根据需要处理
};

​
最佳实践

选择高质量的源图像：
  • 使用主体清晰、光线良好的图像
  • 确保最小分辨率为 512x512 像素
  • 避免高度压缩或低质量的图像
  • 选择有明确焦点的图像以获得更好的动画效果
构图考虑：
  • 具有中心主体的图像最适合动画
  • 考虑镜头运动如何影响构图
  • 避免背景过于复杂的图像
专注于运动和动作：
  • 描述图像中的元素应如何移动或变化
  • 包含镜头运动描述（缩放、平移、旋转）
  • 指定运动的节奏和风格（缓慢、戏剧性、平滑）
好提示词的示例：
  • “雄鹰展开翅膀，以雄伟的慢动作飞行向上翱翔”
  • “镜头缓慢后拉，展现主体后面的广阔山景”
  • “微风轻抚，树叶轻摇，阳光动态地透过树叶洒下”
实现健壮的错误处理：
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;
      
      // 指数退避
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};
处理不同的错误类型：
  • 网络错误：使用指数退避重试
  • 身份验证错误：检查并刷新 API 密钥
  • 验证错误：在重试前修复参数
  • 速率限制：实现适当的退避策略
使用回调提高效率：
  • 实现 webhook 端点而不是轮询
  • 确保您的回调 URL 公开可访问且安全
  • 通过适当的日志记录处理回调失败
监控 API 使用：
  • 跟踪您的 API 使用和积分消耗
  • 在您的端实现速率限制以避免达到 API 限制
  • 记录所有请求和响应以便调试
存储考虑：
  • 根据用户群选择适当的 uploadCn 设置
  • 为 14 天视频保留期制定计划
  • 为重要内容实现自动下载系统

​
相关端点

获取任务详情

检查生成状态并检索视频 URL

回调指南

实现 webhook 进行异步通知
需要帮助？ 请联系我们的支持团队 [email protected] 获取 Runway Alpeh API 的帮助。

授权

​
Authorization
string
header
必填

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

获取 API 密钥：

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

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

注意：

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

请求体

application/json
​
prompt
string
必填

指导 AI 视频转换的描述性文本。请具体描述主题、动作、风格和设置。描述如何根据提示词对参考视频内容进行转换或修改。

示例:

"一只雄鹰在夕阳下的山间云雾中翱翔，配以电影级镜头运动"

​
videoUrl
string
必填

用作视频生成基础的参考视频 URL。AI 将根据提示词对该视频进行转换和增强。

示例:

"https://example.com/input-video.mp4"

​
callBackUrl
string

接收 AI 视频生成任务完成更新的 URL。

  • 当视频生成完成时，系统将向此 URL 发送 POST 请求，包含任务状态和结果
  • 回调包含生成的视频 URL、封面图像和任务信息
  • 您的回调端点应接受包含视频结果的 JSON 负载的 POST 请求
  • 有关详细的回调格式和实施指南，请参阅 Aleph 视频生成回调
  • 或者，使用获取 Aleph 视频详情端点轮询任务状态
示例:

"https://api.example.com/callback"

​
waterMark
string

可选的水印文本内容。空字符串表示无水印，非空字符串将在视频中显示指定文本作为水印。

示例:

"kie.ai"

​
uploadCn
boolean
默认值:false

上传方式选择。默认值为 false（S3/R2），设置为 true 使用阿里云 OSS 上传，设置为 false 使用海外 R2 服务器上传。

示例:

false

​
aspectRatio
enum<string>

视频纵横比。

可用选项:
16:9,
9:16,
4:3,
3:4,
1:1,
21:9
示例:

"16:9"

​
seed
integer

随机种子。用于结果可复现。

示例:

123456

​
referenceImage
string<uri>

参考图像 URL，用于影响输出的风格或内容。

示例:

"https://example.com/reference.jpg"

响应

请求成功

​
code
enum<integer>

响应状态码

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

当 code != 200 时的错误消息

示例:

"success"

​
data
object