欢迎使用 Luma API!

本快速开始指南将引导您完成使用最先进的 AI 模型开始修改视频的基本步骤。

概述

生成的视频是异步处理的。使用回调或轮询来跟踪完成状态。

身份验证

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

获取您的 API Key

访问 API Key 管理页面 获取您的 API key。
2

添加到请求头

在所有请求中包含您的 API key:
Authorization: Bearer YOUR_API_KEY
请保护好您的 API key,永远不要公开分享。如果泄露,请立即在管理页面重置。

基本用法

1. 修改现有视频

首先创建您的第一个视频修改任务:
curl -X POST "https://api.kie.ai/api/v1/modify/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night with towering glass spires reaching into a starry sky. Neon lights in blue and purple illuminate the buildings while flying vehicles glide silently between the structures.",
    "videoUrl": "https://example.com/input-video.mp4",
    "callBackUrl": "https://your-callback-url.com/luma-callback"
  }'
响应:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "774d9a7dd608a0e49293903095e45a4c"
  }
}

2. 检查生成状态

使用返回的 taskId 监控进度:
curl -X GET "https://api.kie.ai/api/v1/modify/record-info?taskId=774d9a7dd608a0e49293903095e45a4c" \
  -H "Authorization: Bearer YOUR_API_KEY"
状态值:
  • 0: 生成中 - 任务正在处理中
  • 1: 成功 - 任务成功完成
  • 2: 创建任务失败 - 无法创建任务
  • 3: 生成失败 - 任务创建成功但生成失败
  • 4: 回调失败 - 生成成功但回调失败

完整工作流示例

这是一个修改视频并等待完成的完整示例:
class LumaAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.kie.ai/api/v1/modify';
  }
  
  async modifyVideo(prompt, videoUrl, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        videoUrl,
        callBackUrl: options.callBackUrl,
        watermark: options.watermark,
        ...options
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`生成失败: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 900000) { // 15 分钟最大
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      if (status.successFlag === 1) {
        return status.response;
      } else if (status.successFlag === 2 || status.successFlag === 3) {
        throw new Error(`生成失败: ${status.errorMessage || '未知错误'}`);
      }
      
      // 下次检查前等待 10 秒
      await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    throw new Error('生成超时');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    return result.data;
  }
}

// 使用示例
async function main() {
  const api = new LumaAPI('YOUR_API_KEY');
  
  try {
    // 视频修改
    console.log('开始视频修改...');
    const taskId = await api.modifyVideo(
      'A futuristic cityscape at night with towering glass spires reaching into a starry sky. Neon lights in blue and purple illuminate the buildings while flying vehicles glide silently between the structures. Holographic advertisements flicker and change on building facades.',
      'https://example.com/input-video.mp4',
      { 
        callBackUrl: 'https://your-callback-url.com/luma-callback',
        watermark: 'your-watermark-id'
      }
    );
    
    // 等待完成
    console.log(`任务 ID: ${taskId}。等待完成...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('视频修改成功!');
    console.log('结果视频 URL:', result.resultUrls);
    console.log('原始视频 URL:', result.originUrls);
    
  } catch (error) {
    console.error('错误:', error.message);
  }
}

main();

高级功能

水印支持

为生成的视频添加水印:
const taskId = await api.modifyVideo(
  '将此场景转换为魔法森林',
  'https://example.com/input-video.mp4',
  {
    watermark: 'your-brand-watermark'
  }
);

使用回调

设置 webhook 回调以获取自动通知:
const taskId = await api.modifyVideo(
  '创建戏剧性的日落转换',
  'https://example.com/input-video.mp4',
  {
    callBackUrl: 'https://your-server.com/luma-callback'
  }
);

// 您的回调端点将收到:
app.post('/luma-callback', (req, res) => {
  const { code, data } = req.body;
  
  if (code === 200) {
    console.log('视频准备就绪:', data.resultUrls);
  } else {
    console.log('生成失败:', req.body.msg);
  }
  
  res.status(200).json({ status: 'received' });
});

了解更多关于回调

设置 webhook 回调以在视频准备就绪时接收自动通知。

错误处理

常见错误场景及处理方法:

最佳实践

性能优化

  1. 使用回调:设置 webhook 回调而不是轮询以获得更好的性能
  2. 提示工程:使用详细、具体的提示以获得更好的结果
  3. 视频预处理:确保输入视频经过优化且可访问
  4. 下载管理:及时下载生成的视频,因为它们可能会过期
  5. 错误处理:实施强大的错误处理和重试逻辑

重要限制

  • 语言支持:提示仅支持英语
  • 视频存储:生成的视频可能在一定时间后过期
  • 文件大小:最大视频大小为 500MB
  • 时长:最大视频时长为 10 秒
  • 输入视频:必须是可公开访问的 URL
  • 处理时间:视频生成可能需要几分钟

支持的参数

核心参数

参数类型描述必填
promptstring必填。视频修改的文本描述
videoUrlstring必填。用于修改的输入视频 URL

可选参数

参数类型描述默认值
callBackUrlstringWebhook 通知 URL-
watermarkstring水印标识符-

下一步

支持

需要帮助?以下是您的选择:
  • 技术支持support@kie.ai
  • API 状态:监控服务健康和公告
  • 文档:探索详细的 API 参考
  • 社区:加入我们的开发者社区获取提示和示例
准备创建令人惊叹的 AI 修改视频?从上面的示例开始,探索完整的 API 功能!