# Project Creation

The first step in Shuffll's pipeline is creating a project. A project represents a single video — its script, scene structure, media, voiceover, and settings. Once created, Shuffll automatically begins enhancement and, if configured, export.

## How it works

1. You call `POST /auth/project/create` with a prompt (or link, script, etc.).
2. Shuffll's AI generates a structured script divided into scenes.
3. Visuals are assembled for each scene using the media fallback system.
4. The project enters enhancement automatically.


## Prompt types

The `promptType` field controls what Shuffll treats the `prompt` value as:

| `promptType` | What Shuffll does |
|  --- | --- |
| `Prompt` *(default)* | Treats `prompt` as a free-text topic description and generates a full script |
| `Link` | Scrapes the public URL provided in `prompt` and bases the script on that content |
| `Docs` | Reads the Google Doc at the URL in `prompt` |
| `Slides` | Reads the Google Slides presentation at the URL in `prompt` |
| `Script` | Uses `prompt` as the final script verbatim — no AI script generation |


## Simple example

Create a short marketing video from a text prompt with full automation:


```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": "Why our SaaS product saves marketing teams 10 hours a week",
    "promptType": "Prompt",
    "language": "en",
    "videoLength": "medium",
    "toAutoEnhance": true,
    "toAutoExport": true,
    "webhook": "https://yourserver.com/webhooks/shuffll"
  }'
```

**Response:**


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

## Key request fields

| Field | Type | Description |
|  --- | --- | --- |
| `prompt` | string | The input text, URL, or script |
| `promptType` | string | One of `Prompt`, `Link`, `Docs`, `Slides`, `Script` |
| `language` | string | Output language code, e.g. `en`, `es`, `fr`. Use `auto` to detect from the prompt |
| `videoLength` | string | `short` (~60s), `medium` (~90s), `long` (~120s) |
| `storyTellingTechnique` | string | Technique ID from `GET /auth/config/storytelling_techniques` |
| `toneOfVoice` | string | Tone ID from `GET /auth/config/tone_of_voice` |
| `videoTagId` | string | Category ID from `GET /auth/config/video_tags` |
| `toAutoEnhance` | boolean | If `true`, enhancement starts automatically after creation |
| `toAutoExport` | boolean | If `true`, export runs automatically after enhancement |
| `webhook` | string (URL) | Receives a `POST` when the export completes |
| `additionalParams` | object | Any custom metadata to echo back in the webhook payload |


## Voice and avatar settings

To set a specific AI voice, retrieve options from `GET /auth/config/ai_voice_options` and pass the voice ID:


```json
"aiVoiceSettings": {
  "voiceId": "voice_abc123",
  "voiceType": "openai",
  "voiceInstructions": "Speak enthusiastically and clearly"
}
```

To use an AI avatar presenter, retrieve options from `GET /auth/config/ai_avatar_options`:


```json
"aiAvatarSettings": {
  "avatarId": "avatar_xyz789"
}
```

## Creating from a template

To use a specific template for scene structure and visual style, add a `customTemplate` object:


```json
"customTemplate": {
  "id": "template_id_here",
  "flexibilityOverride": "minor"
}
```

See [Using Templates](/guides/workflow-templates) for the full guide on template customization options.

## Polling creation status

After creating a project, poll until `status` is `DONE`:


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

| `status` value | Meaning |
|  --- | --- |
| `STRUCTURE` | Building the storyline and script |
| `GENERATING_IMAGES` | Generating scene visuals |
| `DONE` | Creation complete — enhancement begins automatically |


Recommended polling interval: every 5–10 seconds.