Skip to main content

​
Overview

The Nouvel API uses API keys with Bearer token authentication. All requests must include your API key in the Authorization header.
Never expose your API keys in client-side code, version control, or public repositories. API keys grant access to your account and quota.

​
API Key Format

All Nouvel API keys use the prefix nvl_ followed by a unique identifier: 
nvl_xxxxxxxxxxxxxxxxxxxx

​
Creating an API Key

1

Navigate to Settings

Log in to your Nouvel account and go to Settings → API Keys
2

Click 'Create API Key'

You can create up to 5 API keys per account
3

Configure the key

  • Name: A descriptive name for identification (e.g., “Production Server”)
  • Permissions: Select which operations this key can perform
  • Expiration: Choose when the key should expire
4

Copy and store securely

The full API key is only shown once at creation. Store it in a secure location like a password manager or environment variable.
API keys are only available on Scale and Business plans. Upgrade your plan to unlock API access.

​
Permissions

Each API key can have one or more of the following permissions. Choose only the permissions needed for each key to follow the principle of least privilege.
PermissionDescriptionGrants Access To
generateCreate video adsPOST /api/v1/generate
projects:readView project status & listGET /api/v1/jobs/{jobId}, GET /api/v1/projects
publishSchedule & publish postsPOST /api/v1/publish, GET /api/v1/publish/{id}
analytics:readView analytics dataGET /api/v1/analytics
copilot:chatUse AI copilot chatPOST /api/v1/copilot/chat
For most use cases, you’ll need at least generate and projects:read permissions to create videos and check their status.

​
Expiration Options

Set an expiration date to automatically revoke keys after a certain period:
OptionDuration
7 daysTemporary testing/development
30 daysShort-term campaigns
90 daysQuarterly rotation
1 yearAnnual rotation
NeverNo expiration (not recommended)
Custom dateSpecific expiration date
Security best practice: Set expiration dates and rotate keys regularly (every 90 days recommended). Never use “Never” for production keys.

​
Using Your API Key

Include your API key in the Authorization header as a Bearer token: 
curl https://app.nouvel.ai/api/v1/generate \
  -H "Authorization: Bearer nvl_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/products/protein-powder"],
    "variantCount": 1
  }'

​
Security Best Practices

Never hardcode API keys in your source code. Use environment variables:
.env
NOUVEL_API_KEY=nvl_xxxxxxxxxxxxxxxxxxxx
Add .env to your .gitignore to prevent accidentally committing it.
Create different API keys for development, staging, and production. This allows you to:
  • Identify which environment made a request
  • Revoke compromised keys without affecting other environments
  • Set different permissions per environment
Set expiration dates and rotate keys every 90 days. When rotating:
  1. Create a new key
  2. Update your application to use the new key
  3. Verify the new key works
  4. Delete the old key
Only grant permissions that are actually needed. For example:
  • Read-only monitoring: projects:read, analytics:read
  • Video generation service: generate, projects:read
  • Publishing automation: publish, projects:read
Regularly check your API keys in the dashboard:
  • Review active keys and their last used date
  • Delete unused or forgotten keys
  • Check for unexpected usage patterns
Never include API keys in:
  • Frontend JavaScript code
  • Mobile app source code
  • Public GitHub repositories
  • Client-side API calls
Always use a backend server or serverless function to make API calls.

​
Error Responses

​
Invalid API Key

{
  "error": "Unable to resolve user from API key"
}
Status Code: 401 Unauthorized Causes:
  • API key is incorrect or malformed
  • API key has been deleted or expired
  • Missing Authorization: Bearer prefix

​
Missing Permission

{
  "error": "This API key does not have the 'generate' permission"
}
Status Code: 403 Forbidden Causes:
  • API key doesn’t have the required permission for this endpoint
  • Solution: Revoke this key and create a new one with the necessary permissions

​
Plan Required

{
  "error": "API access requires a Scale or Business plan"
}
Status Code: 402 Payment Required Causes:

​
Rate Limiting

All API keys are subject to rate limits:
  • 60 requests per minute per API key
  • Rate limit resets every 60 seconds
  • Exceeding the limit returns 429 Too Many Requests
The response includes rate limit headers: 
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1678901234
Implement exponential backoff when you receive a 429 response. Wait for the time specified in X-RateLimit-Reset before retrying.

​
Managing API Keys

​
Viewing Active Keys

Navigate to Settings → API Keys to view all active keys:
  • Key name and creation date
  • Last used timestamp
  • Permissions granted
  • Expiration date

​
Revoking a Key

Click the Delete button next to any key to immediately revoke it. This action is permanent and cannot be undone.
Deleting a key immediately invalidates it. Any applications using that key will receive 401 Unauthorized errors.

​
Key Limit

You can create up to 5 API keys per account. If you need more keys, delete unused ones or contact support for enterprise options.

​
Next Steps

Quickstart

Generate your first video with the API

Generate Endpoint

Learn about the video generation endpoint