Welcome to the Luma API!

This quickstart guide will walk you through the essential steps to start modifying videos using state-of-the-art AI models.

Overview

Generated videos are processed asynchronously. Use callbacks or polling to track completion status.

Authentication

All API requests require authentication via Bearer Token.
1

Get Your API Key

Visit the API Key Management Page to obtain your API key.
2

Add to Request Headers

Include your API key in all requests:
Authorization: Bearer YOUR_API_KEY
Keep your API key secure and never share it publicly. If compromised, reset it immediately in the management page.

Basic Usage

1. Modify an Existing Video

Start by creating your first video modification task:
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"
  }'
Response:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "774d9a7dd608a0e49293903095e45a4c"
  }
}

2. Check Generation Status

Use the returned taskId to monitor progress:
curl -X GET "https://api.kie.ai/api/v1/modify/record-info?taskId=774d9a7dd608a0e49293903095e45a4c" \
  -H "Authorization: Bearer YOUR_API_KEY"
Status Values:
  • 0: GENERATING - Task is currently being processed
  • 1: SUCCESS - Task completed successfully
  • 2: CREATE_TASK_FAILED - Failed to create the task
  • 3: GENERATE_FAILED - Task creation succeeded but generation failed
  • 4: CALLBACK_FAILED - Generation succeeded but callback failed

Complete Workflow Example

Here’s a complete example that modifies a video and waits for completion:
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 (!response.ok || result.code !== 200) {
      throw new Error(`Generation failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 900000) { // 15 minutes max
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      switch (status.successFlag) {
        case 0:
          console.log('Task is generating, continue waiting...');
          break;
          
        case 1:
          console.log('Generation completed successfully!');
          return status.response;
          
        case 4:
          console.log('Generation succeeded but callback failed');
          return status.response;
          
        case 2:
          const createError = status.errorMessage || 'Task creation failed';
          console.error('Task creation failed:', createError);
          if (status.errorCode) {
            console.error('Error code:', status.errorCode);
          }
          throw new Error(createError);
          
        case 3:
          const generateError = status.errorMessage || 'Task created successfully but generation failed';
          console.error('Generation failed:', generateError);
          if (status.errorCode) {
            console.error('Error code:', status.errorCode);
          }
          throw new Error(generateError);
          
        default:
          console.log(`Unknown status: ${status.successFlag}`);
          if (status.errorMessage) {
            console.error('Error message:', status.errorMessage);
          }
          break;
      }
      
      // Wait 10 seconds before next check
      await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    throw new Error('Generation timeout');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`Status check failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data;
  }
}

// Usage Example
async function main() {
  const api = new LumaAPI('YOUR_API_KEY');
  
  try {
    // Video Modification
    console.log('Starting video modification...');
    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'
      }
    );
    
    // Wait for completion
    console.log(`Task ID: ${taskId}. Waiting for completion...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('Video modified successfully!');
    console.log('Result Video URLs:', result.resultUrls);
    console.log('Original Video URLs:', result.originUrls);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

Advanced Features

Watermark Support

Add watermarks to your generated videos:
const taskId = await api.modifyVideo(
  'Transform this scene into a magical forest',
  'https://example.com/input-video.mp4',
  {
    watermark: 'your-brand-watermark'
  }
);

Using Callbacks

Set up webhook callbacks for automatic notifications:
const taskId = await api.modifyVideo(
  'Create a dramatic sunset transformation',
  'https://example.com/input-video.mp4',
  {
    callBackUrl: 'https://your-server.com/luma-callback'
  }
);

// Your callback endpoint will receive:
app.post('/luma-callback', (req, res) => {
  const { code, data } = req.body;
  
  if (code === 200) {
    console.log('Videos ready:', data.resultUrls);
  } else {
    console.log('Generation failed:', req.body.msg);
  }
  
  res.status(200).json({ status: 'received' });
});

Learn More About Callbacks

Set up webhook callbacks to receive automatic notifications when your videos are ready.

Error Handling

Common error scenarios and how to handle them:
try {
  const taskId = await api.modifyVideo('prompt', 'invalid-url');
} catch (error) {
  if (error.data.code === 422) {
    console.log('Please provide a valid, accessible video URL');
  }
}
try {
  const result = await api.waitForCompletion(taskId);
} catch (error) {
  console.log('Generation failed. Try adjusting your prompt or video input');
}
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function generateWithRetry(prompt, videoUrl, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await api.modifyVideo(prompt, videoUrl, options);
    } catch (error) {
      if (error.data.code === 429 && i < maxRetries - 1) {
        await delay(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

Best Practices

Performance Optimization

  1. Use Callbacks: Set up webhook callbacks instead of polling for better performance
  2. Prompt Engineering: Use detailed, specific prompts for better results
  3. Video Preprocessing: Ensure input videos are optimized and accessible
  4. Download Management: Download generated videos promptly as they may expire
  5. Error Handling: Implement robust error handling and retry logic

Important Limitations

  • Language Support: Prompts only support English
  • Video Storage: Generated videos may expire after a certain period
  • File Size: Maximum video size is 500MB
  • Duration: Maximum video duration is 10 seconds
  • Input Videos: Must be publicly accessible URLs
  • Processing Time: Video generation can take several minutes

Supported Parameters

Core Parameters

ParameterTypeDescriptionRequired
promptstringRequired. Text description for video modification
videoUrlstringRequired. URL of input video for modification

Optional Parameters

ParameterTypeDescriptionDefault
callBackUrlstringWebhook notification URL-
watermarkstringWatermark identifier-

Task Status Descriptions

successFlag: 0
Generating
Task is currently being processed
successFlag: 1
Success
Task completed successfully
successFlag: 2
Create Task Failed
Failed to create the task
successFlag: 3
Generate Failed
Task creation succeeded but generation failed
successFlag: 4
Callback Failed
Generation succeeded but callback failed

Next Steps

Support

Need help? Here are your options:
  • Technical Support: support@kie.ai
  • API Status: Monitor service health and announcements
  • Documentation: Explore detailed API references
  • Community: Join our developer community for tips and examples
Ready to create amazing AI-modified videos? Start with the examples above and explore the full API capabilities!