# Shuffll Workflow Overview

Shuffll enables seamless AI-powered video creation, allowing businesses and developers to generate, enhance, and export videos automatically.

## Integration Options

You can integrate Shuffll in two ways:

1. **[Shuffll API](/apis)** — For full programmatic control over the video creation process.
2. **[Shuffll iFrame](/integrations/iframe-integration)** — Embed Shuffll's project creation wizard directly into your application.


## API Approaches

For API users, there are two different approaches depending on how much control you need:

### 1. Full Sequence: Step-by-Step Control

Use separate API calls for each stage:

- **Create Project** → **Poll Creation Status** → **Poll Enhancement Status** → **Trigger Export** → **Poll Export Status**
- Ideal for applications requiring custom processing, additional editing, or detailed progress tracking.


### 2. AutoEnhance + AutoExport with Webhooks: Full Automation

Use a single API call to create a project and let Shuffll handle everything automatically.

- `toAutoEnhance: true` — post-production (branding, subtitles, audio) runs automatically after creation.
- `toAutoExport: true` — export runs automatically after enhancement completes.
- `webhook` — Shuffll calls your URL when the export is ready; no polling needed.
- Ideal for high-volume automation.


## Polling vs. Webhook Workflow


```
Polling workflow:

  POST /auth/project/create
       ↓
  GET  /auth/project/{id}/create/status   ← poll until status = DONE
       ↓
  GET  /auth/project/{id}/edit/status/enhance  ← poll until isDone = true
       ↓
  POST /auth/project/{id}/edit/export
       ↓
  GET  /auth/project/{id}/edit/status/export  ← poll until isDone = true
       ↓
  Retrieve urls.uploadPath

Webhook workflow (toAutoEnhance + toAutoExport):

  POST /auth/project/create  (set toAutoEnhance, toAutoExport, webhook)
       ↓
  Wait for webhook POST to your server
       ↓
  Retrieve urls.uploadPath from webhook payload
```

## Polling vs. Webhooks Comparison

| Feature | Polling | Webhook |
|  --- | --- | --- |
| Granular progress tracking | Yes | No |
| Minimal API calls | No | Yes |
| Requires a public server endpoint | No | Yes |
| Best for high-volume automation | No | Yes |


**Choose polling** if you need full control, custom logic, or manual review at each stage.
**Choose webhooks** if you want hands-free, fully automated video creation.

## Webhook Payload

When your export completes, Shuffll sends a `POST` to your `webhook` URL with the following body:


```json
{
  "type": "export",
  "payload": {
    "projectId": "6947b539cc95ea68854bb523",
    "projectName": "How AI is transforming the marketing industry",
    "urls": {
      "uploadPath": "https://cdn.shuffll.com/.../video.mp4",
      "dashPath": "https://cdn.shuffll.com/.../manifest.mpd"
    },
    "additionalParams": {}
  }
}
```

Use `additionalParams` in your create request to embed any metadata you want echoed back in the webhook payload.

## Webhook Handling Example (Node.js)


```javascript
const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks/shuffll", (req, res) => {
  const { type, payload } = req.body;

  if (type === "export") {
    console.log(`Video ready: ${payload.urls.uploadPath}`);
    // store payload.urls.uploadPath for the user
  }

  res.sendStatus(200);
});

app.listen(3000);
```

## AutoEnhance + AutoExport Example (cURL)


```bash
curl -X POST "https://api.shuffll.com/api/v1/auth/project/create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How AI is transforming the marketing industry",
    "language": "en",
    "videoLength": "medium",
    "toAutoEnhance": true,
    "toAutoExport": true,
    "webhook": "https://yourserver.com/webhooks/shuffll",
    "additionalParams": { "userId": "usr_123" }
  }'
```

## Troubleshooting

**Webhook not receiving calls?**

- Ensure the URL is publicly accessible (not localhost).
- Check that your server returns HTTP 200 promptly; Shuffll may retry on failure.


**Polling hitting rate limits?**

- Use exponential backoff — start at 5 seconds between polls, double after each miss.
- Consider switching to webhooks for high-volume use cases.


## The Full Video Creation Process

1. **[Project Creation](/guides/workflow-project-creation)** — Define the idea, create a script, and structure a storyline.
2. **[Video Generation](/guides/workflow-video-generation)** — Turn the storyline into a full video using AI-driven media.
3. **[Enhancement](/guides/workflow-enhancement)** — Add branding, subtitles, and optimize audio automatically.
4. **[Export](/guides/workflow-export)** — Finalize and retrieve the downloadable video.
5. **[Using Templates](/guides/workflow-templates)** — Control the scene structure, media sources, fonts, and AI flexibility.


## iFrame vs. API

| Feature | API Integration | iFrame Integration |
|  --- | --- | --- |
| Customization | Full control over every step | Pre-built, ready-to-use UI |
| Ease of use | Requires API development | No-code embedding |
| Automation | Fully automatable | Guided creation |
| Best for | Developers and automation | Platforms offering video creation as a service |