Prerequisites
Before you begin, make sure you have:Active Subscription
You need a Scale ($249/mo) or Business ($849/mo) plan to access the API.Upgrade your plan →
API Key
Create an API key with at least
generate and projects:read permissions.Create API key →Don’t have an account yet? Sign up for free and upgrade to a qualifying plan.
Step 1: Create an API Key
Navigate to Settings
Go to Settings → API Keys in your Nouvel dashboard.
Create a new key
Click “Create API Key” and configure:
- Name:
My First API Key(or any descriptive name) - Permissions: Select
generateandprojects:read - Expiration:
30 days(recommended for testing)
Step 2: Generate a Video
Send a POST request to/api/v1/generate with a product URL:
Response
Unique identifier for this generation job. Use this to poll status.
Total number of video variants being generated (urls × variantCount)
Initial job status, always
"running" for new jobsStep 3: Poll for Completion
Video generation takes 2-5 minutes. Poll the status endpoint to track progress:Status Response
Job status:
running, completed, partial, failed, or cancelledOverall progress percentage (0-100)
Current generation stage:
preparing, video, audio, lip_sync, or stitchingArray of individual video projects being generated
Array of completed projects with full metadata (only populated when
status is terminal)Recommended polling interval: 10 seconds. Polling more frequently doesn’t speed up generation and may hit rate limits.
Step 4: Get the Result
Whenstatus becomes completed, the completedDetails array contains your video(s):
Direct download URL for the completed video (MP4 format, publicly accessible)
Full voiceover script used in the video
Video aspect ratio:
9:16 (vertical), 1:1 (square), or 16:9 (landscape)Video duration in seconds (typically 15)
Full Working Example
Here’s a complete TypeScript example that generates a video and waits for completion:nouvel-generate.ts
Understanding Generation Time
Video generation typically takes 15-20 minutes and goes through these stages:| Stage | Duration | Description |
|---|---|---|
preparing | ~1 min | Scraping product data, generating ad concept |
video | ~10 min | AI video generation with actors (longest step) |
audio | ~30 sec | Text-to-speech voiceover generation |
lip_sync | ~4 min | Syncing actor’s lips to voiceover |
stitching | ~1 min | Adding captions and final rendering |
Request Parameters
ThePOST /api/v1/generate endpoint accepts these parameters:
Array of 1-3 product URLs to generate videos for. Each URL must be a valid product page (not a category, homepage, or blog).Example:
["https://shop.com/products/shoes", "https://shop.com/products/jacket"]Number of video variants to generate per URL (1-3). Each variant has a different ad angle and actor.Total videos =
urls.length × variantCount (max 9)Optional custom instructions for the AI (max 2000 characters). Use this to specify:
- Target audience (e.g., “Target women aged 25-35”)
- Ad angle (e.g., “Focus on sustainability and eco-friendliness”)
- Tone (e.g., “Professional and trustworthy, not salesy”)
- Specific features to highlight
"Target fitness enthusiasts. Emphasize muscle recovery benefits. Professional tone."Error Handling
Always check the response status and handle errors appropriately:Common Issues
401 Unauthorized
401 Unauthorized
402 Payment Required - Quota Exceeded
402 Payment Required - Quota Exceeded
Cause: You’ve used all videos in your monthly quotaSolution:
- Add credits for overage usage ($8/video)
- Upgrade your plan for higher quota
- Wait until your quota resets at the start of your billing cycle
422 Unprocessable Entity - Not a Product
422 Unprocessable Entity - Not a Product
Cause: The URL is not a valid product pageSolution:
- Ensure the URL points to a specific product, not a category or homepage
- The URL must contain product information (title, description, images)
- Try a different product URL from the same site
429 Too Many Requests
429 Too Many Requests
Cause: Exceeded rate limit of 60 requests/minuteSolution:
- Implement exponential backoff in your polling logic
- Don’t poll more frequently than every 10 seconds
- Spread out your generation requests over time
Job stuck at 99% progress
Job stuck at 99% progress
Cause: Final stitching stage can take 1-2 minutesSolution:
- Continue polling - this is normal
- If stuck for >5 minutes, contact support
Job failed during generation
Job failed during generation
Cause: Various reasons (actor availability, technical issues, etc.)Solution:
- Check the
failedProjectscount in the status response - If
status: "partial", some videos succeeded - checkcompletedDetails - Failed generations don’t count against your quota
- Retry the same URL - it often succeeds on second attempt
Next Steps
Generate Endpoint
Full reference for video generation
Job Status Endpoint
Complete job polling documentation
List Projects
Browse and filter your projects
Need Help?
API Support
Email our team for technical assistance

