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,
  "aspectRatio": "<string>",
  "adDuration": 123,
  "contentType": "<string>",
  "scriptStyle": "<string>",
  "overrideScript": "<string>",
  "userInstructions": "<string>",
  "selectedActorId": "<string>",
  "avatarImageUrl": "<string>",
  "language": "<string>",
  "accent": "<string>",
  "targetAudience": "<string>",
  "formatPreset": "<string>",
  "webhookUrl": "<string>"
}
'

{
  "jobId": "<string>",
  "totalProjects": 123,
  "status": "<string>"
}

POST

api

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,
  "aspectRatio": "<string>",
  "adDuration": 123,
  "contentType": "<string>",
  "scriptStyle": "<string>",
  "overrideScript": "<string>",
  "userInstructions": "<string>",
  "selectedActorId": "<string>",
  "avatarImageUrl": "<string>",
  "language": "<string>",
  "accent": "<string>",
  "targetAudience": "<string>",
  "formatPreset": "<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. Every parameter except urls is optional — the AI auto-determines actor, script style, language, and creative direction from the product page.

Authentication

Authorization

string

required

Your Nouvel API key with generate permission. Format: Bearer nvl_xxxx

Request Body

Required

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

Show Example URLs

[
  "https://example.com/products/protein-powder",
  "https://shop.brand.com/skincare/serum"
]

Generation Settings

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.

aspectRatio

string

default:"9:16"

Video aspect ratio. Valid values:

Value	Description
`9:16`	Vertical / portrait (TikTok, Reels, Shorts)
`16:9`	Horizontal / landscape (YouTube, web)
`1:1`	Square (Instagram feed)

adDuration

integer

default:"15"

Target video duration in seconds. Valid values: 15, 30, 45, 60.

contentType

string

default:"ad"

Content purpose. ad generates a direct-response ad with a CTA. organic generates a softer, editorial-style video.Valid values: ad, organic

Script & Style

scriptStyle

string

default:"problem_solution"

Script framework for the AI copywriter. Determines the narrative structure.

Value	Description
`problem_solution`	Pain point → product as the fix. Universal workhorse. (default)
`three_reasons`	Listicle format — “3 reasons this works.” High retention.
`discovery`	”I just found this…” — curiosity gap, insider authority.
`social_proof`	Comment reply format — leverages reviews and real conversations.
`special_offers`	Promo, discount, FOMO — “this deal won’t last.”
`storytelling`	Brand narrative arc — origin, mission, emotional connection.
`benefits`	Direct value proposition — clean, benefit-driven sell.
`how_to`	Tutorial / educational — step-by-step, high retention.
`emotional`	Transformation story — before/after, aspirational.
`gen_z`	TikTok-native, casual, high relatability.

overrideScript

string

Provide your own voiceover script. When set, the AI skips script generation entirely and uses this text as the voiceover. Maximum 5000 characters.

The script is still processed for lip-sync timing and caption alignment, but the words are exactly what you provide.

userInstructions

string

Free-form creative directions for the AI. Maximum 2000 characters. Use this for nuanced guidance that doesn’t fit into the structured parameters.

Show Example Instructions

“Focus on the eco-friendly packaging and sustainability angle”
“Use an energetic, upbeat tone with fast pacing”
“Emphasize the science behind the product with authority”
“Keep it casual and relatable, like a friend’s recommendation”

User instructions are the highest-priority creative input — they override default AI choices for style, actor, script, and visual direction.

Actor & Avatar

selectedActorId

string

UUID of a specific actor from your Nouvel account. When set, the AI uses this actor for all avatar scenes instead of auto-selecting.

If omitted, the AI auto-selects an actor based on the product category and target audience. For example, beauty products default to a female actor; fitness supplements default to a male actor.

avatarImageUrl

string

HTTPS URL to a custom avatar photo. Use this to generate a video with any person’s likeness instead of a Nouvel stock actor.The image should be:

A clear, front-facing headshot or upper-body photo
At least 512×512 pixels
JPEG, PNG, or WebP format

You are responsible for having the rights to use any custom avatar image. Nouvel does not verify image ownership.

Language & Localization

language

string

default:"auto"

Language for the voiceover script. When set to auto or omitted, the language is auto-detected from the product page.Common values: en (English), es (Spanish), fr (French), de (German), pt (Portuguese), ja (Japanese), ko (Korean), zh (Chinese), hi (Hindi), ar (Arabic).

Show All supported languages

en, es, fr, de, pt, it, nl, pl, ru, ja, ko, zh, hi, ar, tr, sv, no, th, vi, id, ms, tl, cs, ro, el, bg, hr, bn

accent

string

Voice accent override. When omitted, the accent is auto-determined from the language (e.g., English defaults to American).For English, valid accents include: American English accent, British English accent, Australian English accent, Indian English accent, Canadian English accent.

Audience

targetAudience

string

Description of your target audience. Maximum 500 characters. The AI tailors the script tone, vocabulary, hook strategy, and actor selection to match.

Show Example Audiences

“Women 25-35 interested in clean beauty and natural skincare”
“Male fitness enthusiasts aged 18-30 who follow gym culture on TikTok”
“Busy parents looking for convenient, healthy meal solutions”
“Tech-savvy professionals aged 30-45 who value productivity tools”

Advanced

formatPreset

string

Visual layout preset ID. Controls the scene structure and narrative arc. Contact support for available preset IDs.

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

Nouvel retries failed deliveries up to 3 times with exponential backoff (immediate → 10s → 60s).

See the Webhooks guide for payload format, signature verification, and retry behavior.

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

Code	Description
400	Invalid JSON body, invalid URL format, or invalid parameter value. Check the `error` message for details.
401	Invalid or missing API key
402	Quota exceeded. Check `usage` object for current limits.
403	API key missing `generate` permission
422	URL recognized as non-product page (blog, homepage, etc.)
500	Internal server error

How It Works

Product Analysis

The AI scrapes the product page, extracting:

Product name, description, and benefits
Images and branding
Language and pricing

Script Generation

A proprietary model trained on hundreds of high-performing ad scripts generates a voiceover script using the selected scriptStyle. Supports 30+ languages.

Scripts are optimized for natural speech patterns
Word count is enforced server-side to match the target duration

Visual Concept

AI selects the best product photos, generates feature badges, headline text, and CTA copy based on the script and scraped product data.

Video Production

Synthesizes natural voiceover from the script
Generates a lip-synced avatar speaking the hook
Composes product slides with animated transitions
Renders the final video with captions

Final Delivery

Exports MP4 files in your selected aspect ratio, optimized for social platforms.

Generation is asynchronous. This endpoint returns immediately with a jobId. Videos take 2-5 minutes to generate. Poll /api/v1/jobs/{jobId} for status updates, or use a webhookUrl to be notified on completion.

Auto-Detection Defaults

When you submit just a URL, the AI auto-determines everything:

Parameter	Auto-Detection Logic
Actor	AI selects based on product category gender rules (beauty → female, fitness → male)
Language	Detected from product page metadata, defaults to English
Accent	Matched to language (English → American, Spanish → Spanish accent)
Script style	Defaults to `problem_solution`
Duration	15 seconds
Aspect ratio	9:16 (vertical)

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

Start simple, then customize

Send just urls first to see what the AI produces. Then add scriptStyle, targetAudience, or userInstructions to fine-tune results. Over-specifying can constrain the AI unnecessarily.

Use targetAudience for tone matching

Instead of verbose userInstructions, use targetAudience to let the AI adapt vocabulary, hook strategy, and energy level automatically. A “Gen Z TikTok users” audience gets a very different script than “C-suite executives.”

Custom avatars for brand consistency

Use avatarImageUrl with your brand ambassador or influencer’s photo for consistent branding across all videos. Pair with overrideScript for full creative control.

Generate variants for A/B testing

Use variantCount: 2-3 to test different creative approaches. Variants use different scripts, hook strategies, and creative angles automatically.

Monitor generation progress

Poll /api/v1/jobs/{jobId} every 10-15 seconds, or register a webhookUrl to be notified automatically. Check the stage field to see pipeline progress.

Next Steps

After submitting a generation job:

Poll for status: Use Get Job Status to monitor progress — or register a webhook to be notified on completion
Download videos: Once status: "completed", find video URLs in completedDetails[].finalOutputUrl
Publish to social: Use the Publishing API to schedule posts across platforms
Track performance: Use the Analytics API to monitor engagement metrics

Webhooks Get Job Status

⌘I

​Authentication

​Request Body

​Required

​Generation Settings

​Script & Style

​Actor & Avatar

​Language & Localization

​Audience

​Advanced

​Response

​Example Requests

​Response Examples

​Error Codes

​How It Works

​Auto-Detection Defaults

​Billing & Quotas

​Best Practices

​Next Steps

Authentication

Request Body

Required

Generation Settings

Script & Style

Actor & Avatar

Language & Localization

Audience

Advanced

Response

Example Requests

Response Examples

Error Codes

How It Works

Auto-Detection Defaults

Billing & Quotas

Best Practices

Next Steps