Skip to main content
POST
/
api
/
v1
/
generate
Generate Video Ads
curl --request POST \
  --url https://app.nouvel.ai/api/v1/generate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "urls": [
    "<string>"
  ],
  "variantCount": 123,
  "userInstructions": "<string>",
  "webhookUrl": "<string>"
}
'
{
  "jobId": "<string>",
  "totalProjects": 123,
  "status": "<string>"
}
Generate professional UGC-style video ads from product URLs. The AI analyzes product pages, creates scripts, generates video scenes with AI actors, synthesizes voiceovers, and produces fully-edited videos ready for social media.

​
Authentication

​
Authorization
string
required
Your Nouvel API key with generate permission. Format: Bearer nvl_xxxx

​
Request Body

​
urls
string[]
required
Array of 1-3 product page URLs to generate videos from. Each URL must:
  • Be a valid HTTP/HTTPS URL
  • Point to a product page (e.g., Shopify, Amazon, DTC brand sites)
  • Be publicly accessible
​
variantCount
integer
default:"1"
Number of video variants to generate per URL. Must be between 1-3.Total projects = urls.length × variantCount
Each video variant uses a different creative approach (script angle, actor, pacing). Variants help you A/B test what resonates with your audience.
​
userInstructions
string
Custom creative directions for the AI scriptwriter. Maximum 2000 characters.
User instructions are combined with AI-generated product research and competitive ad intelligence to create optimized scripts.
​
webhookUrl
string
HTTPS URL to receive a notification when the job completes (or fails). The URL must:
  • Use HTTPS (HTTP is rejected)
  • Not point to localhost or private IP ranges
When the job reaches a terminal state (completed, partial, or failed), Nouvel will send a POST request to this URL with job details and an X-Nouvel-Signature header for verification.
See the Webhooks guide for payload format, signature verification, and best practices.

​
Response

​
jobId
string
required
UUID of the generation job. Use this to poll status via /api/v1/jobs/{jobId}.
"550e8400-e29b-41d4-a716-446655440000"
​
totalProjects
integer
required
Total number of videos that will be generated (urls.length × variantCount).
​
status
string
required
Job status. Always "running" on successful submission.

​
Example Requests

curl -X POST https://app.nouvel.ai/api/v1/generate \
  -H "Authorization: Bearer nvl_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/products/protein-powder"]
  }'

​
Response Examples

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalProjects": 2,
  "status": "running"
}

​
Error Codes

CodeDescription
400Invalid JSON body, invalid URL format, or parameters out of range
401Invalid or missing API key
402Quota exceeded. Check usage object for current limits.
403API key missing generate permission
422URL recognized as non-product page (blog, homepage, etc.)
500Internal server error

​
How It Works

1

Product Analysis

The AI scrapes the product page, extracting:
  • Product name, description, and benefits
  • Images and branding
  • Target audience signals
  • Price points and positioning
2

Competitive Research

Analyzes top-performing ads in your product category using the Foreplay ad intelligence database.
3

Script Generation

Creates UGC-style scripts optimized for social media, combining:
  • Product research
  • Competitive insights
  • Your custom instructions
  • Platform best practices (TikTok, Instagram Reels, etc.)
4

Video Production

  • Generates scenes using AI actors (Kling O3 text-to-video)
  • Synthesizes natural voiceover (ElevenLabs TTS)
  • Applies lip sync to match voiceover
  • Adds animated captions with perfect timing
5

Final Delivery

Exports MP4 files in 9:16 vertical format, optimized for mobile social platforms.
Generation is asynchronous. This endpoint returns immediately with a jobId. Videos take 15-20 minutes to generate. Poll /api/v1/jobs/{jobId} for status updates.

​
Billing & Quotas

  • Each video generated counts as 1 credit toward your monthly quota
  • If your plan quota is exhausted but you have credit balance, overage billing applies at $8/video
  • Generation fails with 402 if both quota and credit balance are exhausted
Example: With a 50-video/month plan:
  • Request 1: urls: [A, B], variantCount: 2 → 4 credits used, 46 remaining
  • Request 2: urls: [C], variantCount: 3 → 3 credits used, 43 remaining

​
Best Practices

  • Use the main product page URL, not a collection/category page
  • Ensure the page is live and publicly accessible
  • Shopify, WooCommerce, Amazon, and custom DTC sites work well
  • Avoid URLs behind authentication/paywalls
  • Specify target audience demographics and psychographics
  • Define the desired tone (energetic, authoritative, casual, etc.)
  • Highlight specific product angles to emphasize
  • Keep instructions clear and concise (under 500 characters is ideal)
  • Use variantCount: 2-3 to test different creative approaches
  • Variants use different scripts, angles, and pacing
  • Compare performance across variants to optimize future generations
  • Poll /api/v1/jobs/{jobId} every 10-15 seconds
  • Check the stage field to see pipeline progress
  • Stop polling when status is terminal (completed, partial, failed)

​
Rate Limits

  • No explicit rate limit on generation requests
  • Concurrent generation jobs are queued automatically
  • Typical queue time: 5-10 minutes during peak hours
  • Each job runs for 15-20 minutes

​
Next Steps

After submitting a generation job:
  1. Poll for status: Use Get Job Status to monitor progress — or register a webhook to be notified on completion
  2. Download videos: Once status: "completed", find video URLs in completedDetails[].finalOutputUrl
  3. Publish to social: Use the Publishing API to schedule posts across platforms
  4. Track performance: Use the Analytics API to monitor engagement metrics
  5. Get AI help: Use the Copilot API for ad strategy and creative ideation