# Quickstart

Shuffll's API lets you create professional AI-generated videos programmatically. This guide walks you through getting your first video from a text prompt to a downloadable MP4 in a few API calls.

## Prerequisites

1. **Create a Shuffll account** at [app.shuffll.com](https://app.shuffll.com/).
2. **Get your API key** — navigate to Account Settings → API Key → Generate.
3. **Find your workspace ID** — call `GET /auth/organization/list` and note the `workspaceId` from the workspace you want to use.


Keep your API key secure and never expose it in client-side code.

## Authentication

Every request requires an `x-api-key` header:


```bash
-H "x-api-key: YOUR_API_KEY"
```

## Step 1 — Create a project

Send a prompt and let Shuffll generate the script, visuals, and voiceover automatically. Set `toAutoEnhance: true` and `toAutoExport: true` so the full pipeline runs without any additional triggers. Add a `webhook` URL to receive a notification when the video is ready.


```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"
  }'
```

**Response:**


```json
{ "projectId": "6947b539cc95ea68854bb523" }
```

Save the `projectId` — you will use it in every subsequent call.

## Step 2 — Poll creation status

The AI takes a moment to build the script and generate scene visuals. Poll this endpoint until `status` is `DONE`.


```bash
curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/create/status" \
  -H "x-api-key: YOUR_API_KEY"
```

**Possible responses:**


```json
{ "status": "STRUCTURE" }         // AI is building the storyline
{ "status": "GENERATING_IMAGES" } // Scene visuals are being created
{ "status": "DONE" }              // Ready — enhancement starts automatically
```

Recommended polling interval: every 5–10 seconds.

## Step 3 — Poll enhancement status

Once creation is `DONE`, Shuffll automatically begins post-production (branding, subtitles, audio cleanup). A `202` response means it is still running; a `200` response means it is complete.


```bash
curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/edit/status/enhance" \
  -H "x-api-key: YOUR_API_KEY"
```

**In progress (HTTP 202):**


```json
{ "percentages": 45, "isDone": false }
```

**Complete (HTTP 200):**


```json
{ "percentages": 100, "isDone": true }
```

## Step 4 — Poll export status (or use a webhook)

If you used `toAutoExport: true`, the export also runs automatically. Poll the export status endpoint — or skip polling entirely if you set a `webhook`.


```bash
curl "https://api.shuffll.com/api/v1/auth/project/6947b539cc95ea68854bb523/edit/status/export" \
  -H "x-api-key: YOUR_API_KEY"
```

**In progress (HTTP 202):**


```json
{ "isDone": false }
```

**Complete (HTTP 200):**


```json
{
  "isDone": true,
  "urls": {
    "uploadPath": "https://cdn.shuffll.com/.../video.mp4",
    "dashPath": "https://cdn.shuffll.com/.../manifest.mpd"
  }
}
```

- `uploadPath` — direct MP4 download URL
- `dashPath` — MPEG-DASH streaming manifest URL


## Webhook alternative (no polling required)

If you set a `webhook` URL in Step 1, Shuffll calls it when the export is complete. Your server receives:


```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 custom metadata (e.g., a user ID or order ID) that you want returned in the webhook payload.

## Next steps

- [Workflow overview](/guides) — understand the full pipeline and polling vs. webhook patterns
- [Using templates](/guides/workflow-templates) — control video structure, media, fonts, and flexibility
- [API Reference](/apis) — full endpoint and schema reference