# Projects

Create, monitor, and manage AI-generated video projects.

## Create project

 - [POST /auth/project/create](https://api-docs.shuffll.com/apis/projects/createproject.md): Create a new AI-powered video project from a prompt, URL, or script.

---

### Prompt Types

| promptType | Description |
|---|---|
| Prompt | A free-text description of the video topic (default) |
| Link | A public URL — Shuffll scrapes the content and uses it as the basis for the script |
| Docs | A Google Docs URL — Shuffll reads the document content |
| Slides | A Google Slides URL — Shuffll reads the slide content |
| Script | A pre-written script — AI generation is skipped, the script is used as-is |

---

### Scene Media — Fallback System

For each scene, Shuffll fills in media content using the following priority order.
If a source doesn't yield results, it automatically tries the next one.

1. Your videos (customTemplate.scenes[].videosToAdd) — Videos you explicitly provide are always used first.
2. Stock footage — Shuffll searches stock video libraries for footage matching the scene content.
3. Workspace assets — Shuffll looks in your workspace asset library for relevant clips.
4. Image → Video animation — A still image is generated (via Stability AI) and animated into a short clip.
5. AI video generation — A full video clip is generated from scratch based on the scene script.

You can override this default order using videoSourcesPipeline. For example, to use only workspace assets and then generate from text, set:
json
"videoSourcesPipeline": ["workspace_assets", "generate_from_text"]


The same fallback logic applies to still images in scene overlays, controlled by imagesSourcePipeline.

---

### Missing Images (toGenerateMissingImages)

Scene templates can have image slots in their dynamic values. If you don't fill those slots:
- toGenerateMissingImages: true → Shuffll generates a contextually relevant image using Stability AI.
- toGenerateMissingImages: false → The slot is left empty (scene renders without the image).

---

### AI Presenter (Avatar)

Set aiAvatarSettings.avatarId to use an AI avatar presenter in the video. Get available avatars from GET /auth/config/ai_avatar_options.

---

### Webhooks

Set webhook to a URL that Shuffll will call when the export completes. The payload sent to your URL will be:

json
{
  "type": "export",
  "payload": {
    "projectId": "...",
    "projectName": "...",
    "urls": { "uploadPath": "...", "dashPath": "..." },
    "additionalParams": { }
  }
}


Use additionalParams to embed any custom data (IDs, metadata) you want returned in the webhook payload.

Set toAutoEnhance: true and toAutoExport: true to fully automate the pipeline: create → enhance → export → webhook, with no polling required.

---

### After creating a project

Project creation is asynchronous. Poll GET /auth/project/{projectId}/create/status until the project is ready.
Enhancement runs automatically. Monitor progress with GET /auth/project/{projectId}/edit/status/enhance.
When enhancement is complete, trigger export with POST /auth/project/{projectId}/edit/export.

## Get project creation status

 - [GET /auth/project/{projectId}/create/status](https://api-docs.shuffll.com/apis/projects/getprojectcreatestatus.md): Poll this endpoint after creating a project to track AI generation progress.

Returns a status field with one of three values:

| status | Meaning |
|---|---|
| STRUCTURE | The AI is building the storyline and script |
| GENERATING_IMAGES | Scene visuals and media are being generated |
| DONE | Project creation is complete — enhancement will begin automatically |

Keep polling until status is DONE. After that, use GET /auth/project/{projectId}/edit/status/enhance to track enhancement progress.

## Get project

 - [GET /auth/project/{projectId}](https://api-docs.shuffll.com/apis/projects/getprojectbyid.md): Retrieve the full details of a specific project, including its current status, name, and workspace.

Use the status field to determine if the project is still being generated:
- STRUCTURE — initial structure is being built
- GENERATING_IMAGES — images and media are being generated
- EDITING — enhancement is running automatically
- DONE — project is ready

## Delete project

 - [DELETE /auth/project/{projectId}](https://api-docs.shuffll.com/apis/projects/deleteproject.md): Permanently delete a project and all associated data.

This action cannot be undone.