Skip to main content
GET
/
api
/
v1
/
projects
/
{projectId}
Get Project
curl --request GET \
  --url https://app.nouvel.ai/api/v1/projects/{projectId}
{
  "project": {
    "id": "<string>",
    "title": "<string>",
    "description": {},
    "status": "<string>",
    "final_output_url": {},
    "aspect_ratio": {},
    "target_duration_seconds": {},
    "product_url": {},
    "quality": {},
    "tone": {},
    "energy": {},
    "pacing": {},
    "caption_style": {},
    "content_mode": {},
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "scenes": [
    {
      "id": "<string>",
      "scene_order": 123,
      "prompt": {},
      "script_text": {},
      "output_url": {},
      "status": "<string>",
      "avatar_id": {},
      "duration_seconds": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "404 Not Found": {},
  "401 Unauthorized": {}
}
Returns comprehensive details about a single video ad project, including all individual scenes, scripts, and generation metadata. Use this endpoint to track project progress or retrieve the final video and scene-level information.

​
Authentication

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

​
Path Parameters

​
projectId
string
required
The unique identifier (UUID) of the project to retrieve. Must be a valid UUID belonging to the authenticated user.

​
Response

​
project
object
Complete project details including all configuration and output URLs.
​
scenes
array
Ordered list of individual scenes that make up the final video. Scenes are returned in playback order.

​
Example Requests

curl https://app.nouvel.ai/api/v1/projects/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer nvl_xxxx"

​
Example Response

{
  "project": {
    "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://storage.supabase.co/videos/final-550e8400.mp4",
    "aspect_ratio": "9:16",
    "target_duration_seconds": 15,
    "product_url": "https://example.com/products/collagen",
    "quality": "high",
    "tone": "professional",
    "energy": "moderate",
    "pacing": "moderate",
    "caption_style": "modern",
    "content_mode": "auto",
    "created_at": "2024-03-15T14:32:10.000Z",
    "updated_at": "2024-03-15T14:48:22.000Z"
  },
  "scenes": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "scene_order": 0,
      "prompt": "Professional female spokesperson in modern bright studio, upright posture, direct eye contact with camera, composed confident expression, medium shot showing full shoulders, neutral warm lighting",
      "script_text": "Your skin loses collagen every single day. But what if you could restore it naturally?",
      "output_url": "https://storage.supabase.co/videos/scene-7c9e6679.mp4",
      "status": "completed",
      "avatar_id": "iris",
      "duration_seconds": 5.2,
      "created_at": "2024-03-15T14:32:11.000Z",
      "updated_at": "2024-03-15T14:38:45.000Z"
    },
    {
      "id": "8d1f7789-8536-51ef-a55c-f18gd2g01bf8",
      "scene_order": 1,
      "prompt": "Close-up of hands pouring marine collagen powder into clear glass of water on modern kitchen counter, natural morning light, product packaging visible in background",
      "script_text": "Our marine collagen is clinically proven to boost skin elasticity by up to 40% in just 8 weeks.",
      "output_url": "https://storage.supabase.co/videos/scene-8d1f7789.mp4",
      "status": "completed",
      "avatar_id": null,
      "duration_seconds": 4.8,
      "created_at": "2024-03-15T14:32:11.000Z",
      "updated_at": "2024-03-15T14:39:12.000Z"
    },
    {
      "id": "9e2g8899-9647-62fg-b66d-g29he3h12cg9",
      "scene_order": 2,
      "prompt": "Professional female spokesperson in modern bright studio, upright posture, direct eye contact with camera, warm engaged expression, medium shot showing full shoulders",
      "script_text": "Join thousands of women who've transformed their skin. Try it risk-free today.",
      "output_url": "https://storage.supabase.co/videos/scene-9e2g8899.mp4",
      "status": "completed",
      "avatar_id": "iris",
      "duration_seconds": 5.0,
      "created_at": "2024-03-15T14:32:11.000Z",
      "updated_at": "2024-03-15T14:40:03.000Z"
    }
  ]
}

​
Error Responses

​
404 Not Found
object
Returned when the project doesn’t exist or doesn’t belong to the authenticated user.
{
  "error": "Project not found"
}
​
401 Unauthorized
object
Returned when the API key is missing, invalid, or lacks the required permissions.
{
  "error": "Unauthorized"
}

​
Notes

Security: Projects can only be accessed by their owner. API keys are scoped to individual user accounts, and attempting to access another user’s project will return a 404 error.
Scene URLs vs Final URL: The individual scene output_url values point to raw scene clips before final processing. The project-level final_output_url is the fully processed video with continuous voiceover, lip sync, and captions applied. Always use final_output_url for production purposes.
Polling for Completion: When monitoring project progress, poll this endpoint every 5-10 seconds until the status field becomes completed or failed. The updated_at timestamp changes whenever generation progresses.
Scene Order: Scenes are always returned in playback order sorted by scene_order. The final video plays scene 0 first, then scene 1, etc.
Avatar Scenes vs Product Scenes: Scenes with an avatar_id feature a human spokesperson. Scenes without an avatar_id (null) are typically product demonstration shots or B-roll footage.
Rate Limiting: This endpoint is rate-limited to 60 requests per minute per API key. See Rate Limits for details.