List Projects

curl --request GET \
  --url https://app.nouvel.ai/api/v1/projects

import requests

url = "https://app.nouvel.ai/api/v1/projects"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://app.nouvel.ai/api/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.nouvel.ai/api/v1/projects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.nouvel.ai/api/v1/projects"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://app.nouvel.ai/api/v1/projects")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.nouvel.ai/api/v1/projects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "projects": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": {},
      "status": "<string>",
      "final_output_url": {},
      "aspect_ratio": {},
      "target_duration_seconds": {},
      "product_url": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123,
    "hasMore": true
  }
}

GET

api

projects

List Projects

curl --request GET \
  --url https://app.nouvel.ai/api/v1/projects

import requests

url = "https://app.nouvel.ai/api/v1/projects"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://app.nouvel.ai/api/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.nouvel.ai/api/v1/projects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.nouvel.ai/api/v1/projects"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://app.nouvel.ai/api/v1/projects")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.nouvel.ai/api/v1/projects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "projects": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": {},
      "status": "<string>",
      "final_output_url": {},
      "aspect_ratio": {},
      "target_duration_seconds": {},
      "product_url": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123,
    "hasMore": true
  }
}

Returns a paginated list of all video ad projects created by the authenticated user. Results are sorted by creation date (newest first) and can be filtered by project status.

Authentication

This endpoint requires a valid API key with the projects:read permission.

Authorization: Bearer nvl_xxxx

Query Parameters

integer

default:1

Page number for pagination (1-indexed). Must be a positive integer.

integer

default:20

Number of results to return per page. Must be between 1 and 100.

string

Filter projects by their current status. Omit to return all projects.Allowed values:

generating - Video scenes are being generated
post_processing - Generating voiceover and lip sync
stitching - Combining scenes with audio and captions
completed - Project is ready with final video
failed - Generation encountered an unrecoverable error
partial - Some scenes completed but project failed overall

Response

array

List of project objects matching the query criteria.

Show Project object properties

string

Unique project identifier (UUID format).

string

Human-readable project title.

string | null

AI-generated description of the video ad concept. May be null for projects still in generation.

string

Current project status. One of: generating, post_processing, stitching, completed, failed, partial.

string | null

HTTPS URL to the final MP4 video file. Only available when status is completed. URL is publicly accessible but unguessable.

string | null

Video aspect ratio. Common values: "9:16" (vertical/mobile), "1:1" (square), "16:9" (horizontal/desktop).

integer | null

Target video duration in seconds. Actual duration may vary slightly.

string | null

Original product URL provided when creating the project.

string

ISO 8601 timestamp when the project was created.

string

ISO 8601 timestamp when the project was last modified.

object

Pagination metadata for navigating through results.

Show Pagination properties

integer

Current page number (1-indexed).

integer

Number of results returned per page.

integer

Total number of projects matching the query.

integer

Total number of pages available.

boolean

Whether additional pages exist beyond the current page.

Example Requests

curl https://app.nouvel.ai/api/v1/projects \
  -H "Authorization: Bearer nvl_xxxx"

curl "https://app.nouvel.ai/api/v1/projects?status=completed&limit=10" \
  -H "Authorization: Bearer nvl_xxxx"

curl "https://app.nouvel.ai/api/v1/projects?page=2&limit=50" \
  -H "Authorization: Bearer nvl_xxxx"

const response = await fetch('https://app.nouvel.ai/api/v1/projects', {
  headers: {
    'Authorization': 'Bearer nvl_xxxx'
  }
});

const data = await response.json();
console.log(`Found ${data.pagination.total} projects`);

const response = await fetch(
  'https://app.nouvel.ai/api/v1/projects?status=completed',
  {
    headers: {
      'Authorization': 'Bearer nvl_xxxx'
    }
  }
);

const data = await response.json();
const completedVideos = data.projects.map(p => ({
  id: p.id,
  title: p.title,
  videoUrl: p.final_output_url
}));

async function getAllProjects() {
  const allProjects = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://app.nouvel.ai/api/v1/projects?page=${page}&limit=100`,
      {
        headers: {
          'Authorization': 'Bearer nvl_xxxx'
        }
      }
    );

    const data = await response.json();
    allProjects.push(...data.projects);
    hasMore = data.pagination.hasMore;
    page++;
  }

  return allProjects;
}

import requests

response = requests.get(
    'https://app.nouvel.ai/api/v1/projects',
    headers={'Authorization': 'Bearer nvl_xxxx'}
)

data = response.json()
print(f"Found {data['pagination']['total']} projects")

import requests

response = requests.get(
    'https://app.nouvel.ai/api/v1/projects',
    params={'status': 'completed', 'limit': 10},
    headers={'Authorization': 'Bearer nvl_xxxx'}
)

data = response.json()
for project in data['projects']:
    print(f"{project['title']}: {project['final_output_url']}")

import requests

def get_all_projects():
    all_projects = []
    page = 1
    has_more = True

    while has_more:
        response = requests.get(
            'https://app.nouvel.ai/api/v1/projects',
            params={'page': page, 'limit': 100},
            headers={'Authorization': 'Bearer nvl_xxxx'}
        )

        data = response.json()
        all_projects.extend(data['projects'])
        has_more = data['pagination']['hasMore']
        page += 1

    return all_projects

Example Response

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Premium Collagen Ad - Vertical",
      "description": "A compelling 15-second ad showcasing the benefits of marine collagen supplement with professional spokesperson and product demo.",
      "status": "completed",
      "final_output_url": "https://app.nouvel.ai/api/cdn/videos/final-550e8400.mp4",
      "aspect_ratio": "9:16",
      "target_duration_seconds": 15,
      "product_url": "https://example.com/products/collagen",
      "created_at": "2026-03-15T14:32:10.000Z",
      "updated_at": "2026-03-15T14:48:22.000Z"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "title": "Skincare Serum - Instagram",
      "description": null,
      "status": "generating",
      "final_output_url": null,
      "aspect_ratio": "9:16",
      "target_duration_seconds": 15,
      "product_url": "https://example.com/products/serum",
      "created_at": "2026-03-15T14:20:05.000Z",
      "updated_at": "2026-03-15T14:25:18.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasMore": true
  }
}

Notes

Security: Only projects belonging to the authenticated user are returned. API keys are scoped to individual user accounts.

Video Availability: The final_output_url is only populated when the project status is completed. For projects still in progress, this field will be null.

Sorting: Results are always sorted by created_at in descending order (newest projects first). Custom sorting is not currently supported.

Rate Limiting: This endpoint is rate-limited to 60 requests per minute per API key. See Rate Limits for details.

Get Job Status Get Project

Getting Started

Core Concepts

Video Generation

Projects

Publishing

Analytics

AI Copilot

List Projects

Authentication

Query Parameters

Response

Example Requests

Example Response

Notes

​Authentication

​Query Parameters

​Response

​Example Requests

​Example Response

​Notes

Authentication

Query Parameters

Response

Example Requests

Example Response

Notes