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 (result.code !== 200) {
      throw new Error(`Generation failed: ${result.msg}`);
    }
    
    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);
      
      if (status.successFlag === 1) {
        return status.response;
      } else if (status.successFlag === 2 || status.successFlag === 3) {
        throw new Error(`Generation failed: ${status.errorMessage || 'Unknown error'}`);
      }
      
      // 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}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    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:

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-

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!